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FOREWORD 

The  National  Communications  System  (NCS)  is  an  organization  of  the  Federal 
Government  whose  membership  is  comprised  of  23  Government  entities.  Its 
mission  is  to  assist  the  President,  National  Security  Council,  Office  of 
Science  and  Technology  Policy,  and  Office  of  Management  and  Budget  in: 

o  The  exercise  of  their  wartime  and  non -wartime 

emergency  functions  and  their  planning  and  oversight 
responsibilities. 

o  The  coordination  of  the  planning  for  and  provisions  of 
National  Security/ Emergency  Preparedness 
communications  for  the  Federal  Government  under  all 
circumstances  including  crisis  or  emergency. 

In  support  of  this  mission,  the  NCS  has  conducted  studies  and  analyses  to 
assess  the  potential  for  serious  damage  to  portions  of  the  Nation's 
telecommunications  infrastructure  due  to  various  threats.  The  purpose  of 
work  is  to  provide  guidance  to  programmers  on  the  TAMI  module  structure. 

Comments  on  this  TIB  are  welcome  and  should  be  addressed  to: 

Office  of  the  Manager 
National  Communications  System 
Attn:  NC-TS 

701  S.  Court  House  Road 
Arlington,  VA  22204-2198 
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A|IOR£  RAOS'CH 
Electronics  Engineer 
Of fide  of  Technology 
and  Standards 
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1.0  Introduction 


The  Office  of  the  Manager,  National  Communications  System  (OMNCS)  Office  of  Technology  and 
Standards  (NT)  is  responsible  for  a  broad  range  of  initiatives  including  Federal  telecommunications 
standards  development,  network  performance  analyses,  and  technology  review.  As  part  of  the  ongoing 
effort  to  analyze  the  performance  of  the  public  switched  network  (PSN)  and  the  programs  of  the  National 
Level  National  Security  and  Emergency  Preparedness  (NS/EP)  Telecommunications  Program  (NLP),  NT 
has  developed  a  number  of  computer-based  models.  Most  recently,  the  Traffic  Analysis  by  Method  of 
Iteration  (TAMI)  model  was  developed  to  measure  the  effects  of  telecommunications  traffic  congestion  in 
stressed  local  and  long  distance  networks. 

1.1  Purpose 

This  document  provides  the  first  of  two  volumes  of  the  TAMI  Programmer’s  Manual.  Together, 
these  volumes  provide  the  software  description  necessary  for  a  programmer  to  support  future 
maintenance  and  enhancements  to  the  TAMI  model.  A  separate  document,  the  TAMI  User’s  Manual, 
provides  the  information  necessary  for  users  who  wish  to  operate  the  model. 

1.2  Scope 

Volume  I  of  the  TAMI  Programmer’s  Manual  documents  the  first  1 1  of  23  modules  that  form  the 
TAMI  model.  It  is  assumed  that  the  reader  has  a  basic  understanding  of  the  PSN  and  a  working  knowledge 
of  the  architectures  of  the  three  major  inter-exchange  carrier  networks  (IEC)  and  the  local  exchange  carrier 
networks  (LEC).  Furthermore,  a  programmer  using  TAMI  should  have  a  working  knowledge  of  the  UNIX 
operating  system  and  the  ‘C’  and  FORTRAN  programming  languages.  A  background  in  voice  teletraffic 
engineering  and  analytical  modeling  and  simulation  is  desirable  to  understand  the  algorithmic  details  of 
the  TAMI  model.  The  TAMI  programmer  will  find  it  useful  to  be  familiar  with  the  references  provided  at  the 
end  of  this  document,  which  describe  previous  TAMI  analyses,  modeling  concepts,  algorithms,  and 
programmer’s  manuals  of  related  software. 

1.3  Background 

The  nation’s  PSNs  continue  to  be  a  focus  of  NCS  modeling  efforts  because  these  networks 
comprise  the  largest,  most  diverse  set  of  telecommunications  assets  in  the  United  States.  Furthermore, 
the  NCS  directs  its  NS/EP  telecommunications  enhancement  activities  toward  the  PSN.  Additionally, 
most  NCS  member  organizations  rely  on  the  PSN  for  conducting  their  NS/EP  responsibilities. 

The  NCS  has  moved  to  measuring  network  performance  using  call  completion  probability  in 
addition  to  connectivity  because  this  approach  captures  the  effects  of  traffic  congestion.  Traffic 
congestion  is  prevalent  during  many  of  the  national  emergencies  and  disasters  of  concern  to  the  OMNCS. 

In  support  of  PSN  traffic  congestion  analyses,  NT  has  developed  the  TAMI  model.  This  model  is 
only  intended  for  use  in  networks  stressed  by  physical  damageand/or  traffic  overload.  This  model 
measures  congestion  in  the  combined  local  and  long-distance  networks  of  the  PSN.  TAMI  evaluates 
congestion  for  ordinary  telephone  users  and  for  NS/EP  users  who  benefit  from  planned  or  existing  NLP 
enhancements.  In  addition  to  measuring  nationwide  congestion,  the  TAMI  model  has  been  expanded  to 
model  regional  congestion  caused  by  focused  overloads.  Focused  overloads  are  common  during  events 
that  only  affect  part  of  the  country,  such  as  earthquakes  and  hurricanes,  during  which  the  affected  region 
may  be  subject  to  unusually  high  volumes  of  traffic  originating  from  the  rest  of  the  country.  As  the  TAMI 
model  continues  to  evolve,  it  provides  a  more  accurate  tool  for  understanding  the  effects  of  congestion  in 
the  PSN. 

The  TAMI  model  has  been  used  by  both  NT  and  the  Office  of  Plans  and  Programs  (NP)  to 
measure  congestion  in  the  PSN  subject  to  damage  from  electromagnetic  pulse  (EMP),  fallout  radiation, 
nuclear  blast  scenarios,  and,  more  recently,  earthquakes.  An  analysis  has  successfully  been  conducted 
to  determine  the  sensitivity  of  the  model’s  network  performance  results  to  network  management  and 
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engineering  assumptions  made  in  the  absence  of  complete  PSN  data.  In  view  of  continued  plans  to 
employ  and  enhance  the  TAMI  model,  this  document  provides  the  first  of  two  Programmer’s  Manual 
volumes.  These  volumes  will  be  supplemented  by  a  User’s  Manual. 

1.4  Organization 

This  report  is  organized  into  three  sections.  Section  1.0  provides  an  introduction,  describing  the 
purpose,  scope,  background,  and  organization. 

Section  2.0  provides  a  high  level  overview  of  the  TAMI  model  and  describes  the 
interrelationships,  data  flow,  and  interfaces  among  of  the  eleven  software  modules  encompassed  by  this 
report. 


Section  3.0  contains  detailed  documentation  of  the  first  1 1  TAMI  software  modules  and  each 
module’s  component  functions. 


\ 


i 
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2.0  High  Level  TAMI  Description 


This  section  provides  a  high  level  overview  of  the  TAMI  Model  from  a  programming  viewpoint.  A 
number  of  NCS  reports  already  exist  which  describe  the  TAMI  algorithms,  assumptions,  and  modeling 
techniques  (References  2,  3,  5,  6).  The  purpose  of  this  overview  is  to  focus  on  the  interrelationships, 
data  flow,  and  interfaces  among  the  software  modules  that  constitute  the  TAMI  model. 

The  TAMI  model  can  be  divided  into  six  main  functional  processes,  depicted  in  Exhibit  2.1.  Each 
of  these  processes  operate  on  both  IEC  and  LEC  data  and  can  be  described  at  more  detailed  levels. 

Exhibit  2.1 

TAMI  High-Level  Flow  Diagram 


CD  Monte  Carlo  Sampling  Loop 


In  addition  to  QTCM,  which  has  been  previously  documented  as  a  stand-alone  model,  there  are 
23  TAMI  modules  totaling  an  estimated  30,000  lines  of  code.  Exhibit  2.2  identifies  each  of  these 
modules,  categorized  by  the  six  functional  areas  above.  It  also  provides  the  approximate  lines  of  code  for 
each  module  and  indicates  whether  it  appears  in  Volume  I  or  Volume  II  of  the  TAMI  Model  Programmer’s 
Manual.  As  shown,  Volume  I  encompasses  the  pre-processing  of  the  undamaged  IEC  networks  and  the 
generation  of  sampling  pools  of  EMP  damage  vectors.  These  two  functional  areas  are  discussed  in  more 
detail  in  Sections  2.1  and  2.2  respectively.  Exhibits  2.3  and  2.4  provide  a  diagrammatic  road  map  to  these 
sections,  depicting  the  overall  data  flow  for  AT&T,  MCI,  and  Sprint  network  data  through  the  Volume  I 
modules. 
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Exhibit  2.2 

Table  of  TAMI  Modules 


Functional  Area  Within  TAMI 

Module  Name 

Approx  Lines 
of  Code 

|  Vol  1 

Vol  II 

Pre-Process  Undamaged  Network  and  Traffic 

IEC  Networks 

cg_make 

200 

span_make 

300 

array_make 

200 

mk_ncam_path 

4800* 

rem_dup 

200 

sort_path 

130 

3ch_4ch 

200 

matchjrunk 

830 

/ 

mkpath 

275 

✓ 

LEC  Networks  and 

attlive 

900 

/ 

End-to-End  Traffic  Matrix 

mcilive 

1300 

/ 

sprlive 

1300 

/ 

Generate  Pool  of  Damage  Vectors 

damage 

1600 

/ 

mklink 

500 

/ 

Monte  Carlo  Sampling  Loop 

tami 

650 

■ 

Pre-Process  Damaged  Network  and  Traffic 

■ 

mm 

IEC  Networks 

mkrout 

700 

n 

qtrans_gen 

800 

Hi 

LEC  Networks  and 

attwdmg 

2300 

End-to-End  Traffic  Matrix 

mciwdmg 

2300 

■H 

sprwdmg 

2300 

mm 

merge 

850 

H 

Perform  Blockage  Calculations 

LEC  Networks 

lecam 

4500 

✓ 

IEC  Networks 

qtcm 

N/A 

N/A 

N/A 

Post-Process  Analysis  Results 

300 

/ 

*  Includes  code  linked  from  IDA/CAM  model,  Reference  4 


\ 
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Exhibit  2.3 

AT&T  and  Sprint  Data  Flow  Through  Volume  I  TAMI  Modules 
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Exhibit  2.4 

MCI  Data  Flow  Through  Volume  I  TAMI  Modules 


node_dat.icf 
link  dat.icf 


node_dat.icf 
link  dat.icf 


node_dat.icf 

link_dat.icf 

cg_dat.icf 

pid_dat.icf 


Link  Array  File 
array_make.out 


mk_ncam_path 


Location-to-Location 
Path  File 

mk_ncam_path.out 


♦ 

rem_dup 

sort_path 


Location-to-Location 
Path  File  (filtered) 
sort_path.3ch.out 


Switch/ Location  File 
swloc.map 


3ch  4ch 


Switch-to-Switch 
Path  File 
3ch  4ch.out  — 


SpanType  File 
span_make.out 

Switch  File 
switch.dat 


cg_dat.icf 

node_dat.icf 


cg_make 


Switch  File 
switch.dat 


damage 


mklink 


Trunk  Size  File  Path/Trunk  File 
cg_make.out  mkpath.out 


Span  Damage  File 
span_dam.dat 
Switch  Damage  File 
switch_dam.dat 


Switch  File 
switch.dat 


Matched  Trunk  File 
mat_trk.trk.out 
Matched  Path  File 
mat_trk.path.out 


Switch-to-Switch 
Path  File  (filtered) 
rem_dup  .4ch.out 


rem_dup 

sort_path 


|  Damaged  IEC  File  j 
mklink.out 
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2.1  Pre-processing  the  Undamaged  IEC  Networks 

There  are  three  goals  to  this  stage:  (1 )  to  reformat  the  IEC  data  from  ICF  format  (see  Appendix  A) 
into  a  format  usable  by  TAMI,  (2)  to  address  data  anomalies  or  gaps,  and  (3)  to  produce  a  mapping 
between  the  physical  and  logical  IEC  network  descriptions.  This  section  describes  each  of  the  nine 
modules  used  to  perform  the  pre-processing  objectives  on  the  undamaged  IEC  networks.  Because  each 
IEC  data  set  has  unique  anomalies,  some  modules  provide  the  option  to  specify  the  IEC  or  were  designed 
to  be  run  only  on  a  specific  carrier’s  data. 


The  first  four  modules,  cg_make,  span_make,  array_make,  and  mk_ncam_path,  are  designed  to 
reformat  the  ICF  files  so  they  can  be  used  by  TAMI.  Each  of  these  modules  is  generic  (i.e.  runs  the  same 
on  each  IEC)  and  uses  hard  coded  input  and  output  file  names.  The  four  ICF  input  files  are  as  follows  (see 
Appendix  A  for  further  description): 


node_dat.icf 

link_dat.icf 

cg_dat.icf 

pid_dat.icf 


describes  all  IEC  network  nodes,  including  switches,  repeaters,  etc. 
describes  the  links  (or  spans)  between  nodes 
describes  the  logical  circuit  groups  (trunk  groups)  in  the  IEC  backbone 
identifies  the  physical  transmission  paths  (chains  of  spans)  that  connect 
the  backbone  switches 


Each  of  these  four  modules  is  described: 


cg_make: 


span_make: 


array_make: 


This  module  uses  the  cg_dat.icf  and  node_dat.icf  files  to  decode  the  ICF’s 
numerical  circuit  group  format  into  an  easy-to-read  trunk  group  file  based  on 
standard  CLLI  codes.  It  outputs  a  file  called  ‘cg_make.out.’  For  Sprint  only, 
the  circuit  groups  in  the  1993  ICF  files  were  maintained  as  DSIs.  A  standard 
UNIX  utility  called  ‘nawk’  was  used  to  multiply  to  trunk  size  field  by  24  to 
convert  to  DSOs. 

This  module  uses  the  node_dat.icf  and  link_dat.icf  files  to  produce  a  span 
type  file  in  the  format  traditionally  used  for  NCAM  EMP  damage.  Span  types, 
such  as  fiber  optic,  microwave,  and  T1,  are  converted  from  the  codes  used  in 
ICF  to  the  equipment  type  codes  used  for  EMP  damage.  Span_make 
produces  the  output  file  ‘span_make.out.’ 

This  module  almost  the  same  as  span_make,  except  that  the  output  span  file 
it  produces  is  stored  in  an  indexed  numeric  format  in  a  binary  file.  This  output 
file,  ‘array_make.out,’  is  read  by  mk_ncam_path  to  assist  it  in  building  paths 
from  spans. 


mk_ncam_path:  This  module  uses  all  four  ICF  files  as  well  as  the  output  file  from  array_maka  to 

build  a  physical  transmission  path  file  in  the  format  used  by  TAMI.  This  output 
file  is  called  ‘mk_ncam_path.out.’ 

The  next  three  modules,  rem_dup,  sort_path,  and  3ch_4ch,  were  designed  specifically  to  address 
anomalies  in  MCl’s  1 993  path  data.  Each  of  these  modules  performs  a  specific  data  filtering  step  on  the 
‘mk_ncam_path.out’  file  as  described  below: 


3ch_4ch:  MCl’s  1993  path  data  does  not  use  4  character  switch  codes  as  endpoints, 

but  uses  3  character  location  codes.  (This  characteristic  has  been  changed  in 
more  recent  versions  of  the  data,  so  3ch_4ch  may  not  be  needed  in  the 
future.)  Because  some  locations  house  more  than  one  switch,  a  path  that 
ends  at  such  a  location  implies  a  multiplicity  of  paths  to  each  switch  in  the 
building.  This  module  addresses  this  data  anomaly  by  mapping  each 
location-to-location  path  record  to  all  possible  combinations  of  switch-to- 
switch  path  records.  In  addition  to  the  location-to-location  input  path  file,  it 
uses  a  list  of  4  character  switches  and  corresponding  3  character  location 
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codes  to  produce  the  output  switch-to-switch  path  file.  All  of  these  files  have 
user-specified  names. 

rem_dup:  MCPs  1 993  path  data  contains  a  number  of  duplicate  records  which 

needlessly  enlarge  the  size  of  the  ‘mk_ncam_path.out’  file.  Rem_dup 
compares  each  path  record  to  the  previous  two  records  to  remove  adjacent 
duplicates.  The  resulting  output  file  has  a  user-specified  name  (usually  called 
‘rem_dup.out’),  and  is  used  as  the  filtered  path  file  for  subsequent  steps.  To 
fully  prevent  the  possibility  of  duplicate  records,  this  module  is  run  on  both 
the  location-to-location  path  file  (prior  to  3ch_4ch)  and  on  the  switch-to- 
switch  path  file  output  by  3ch_4ch. 

sort_path:  This  module  sorts  the  records  in  the  path  file  alphabetically  by  the  CLLI  codes 

of  the  originating  and  terminating  path  endpoints  in  order  to  group  paths 
between  the  same  switches.  Subsequent  modules  expect  the  path  file  to  be 
ordered  in  this  manner.  The  resulting  output  file  has  a  user-specified  name 
(usually  called  ‘sort_path.out’),  and  is  used  as  the  filtered  path  file  for 
subsequent  steps.  Sort_path  is  run  together  with  rem_dup  on  both  the 
location-to-location  path  file  (prior  to  3ch_4ch )  and  on  the  switch-to-switch 
path  file  output  by  3ch_4ch. 

The  final  two  modules,  mat_trk  and  mkpath,  perform  the  task  of  mapping  the  logical  trunk  groups 
to  the  physical  transmission  paths.  The  final  output  file  combines  logical  and  physical  network  data  to 
describe  the  number  of  trunk  groups  per  path.  This  trunk  group  per  path  breakdown  facilitates  the  later 
task  of  determining  the  impact  of  a  damaged  path  on  the  overall  trunk  group  capacity  between  two 
switches.  In  this  manner,  physical  damage  can  be  correlated  to  reduced  network  capacity.  Mat_trk and 
mkpath  are  described  as  follows: 

mat_trk:  This  module  divides  trunk  group  quantities  among  the  physical  paths.  For 

example,  if  there  are  72  trunks  (3  DSIs)  in  the  trunk  group  from  switch  A  to 
switch  B,  and  three  distinct  physical  paths  between  A  and  B,  mat_trk assigns 
24  trunks  to  each  physical  path.  Each  record  in  the  output  trunk  group  file  will 
therefore  have  a  one-to-one  correspondence  with  paths  in  the  output  path 
file.  Mat_trk also  checks  path  and  trunk  group  endpoints  against  a  list  of 
backbone  switches  to  make  sure  that  only  paths  and  trunk  groups  that 
originate  and  terminate  within  the  toll  network  are  used.  MaLtrk  addresses 
cases  where  there  are  mismatches  between  the  trunk  group  file  and  the  path 
file-where  either  a  trunk  group  exists  without  a  corresponding  path,  or  a  path 
exists  without  a  corresponding  trunk  group. 

mkpath:  The  mkpath  module  combines  each  record  of  the  mat_trk output  trunk  file  to 

the  corresponding  record  in  the  mat_trk output  path  file.  In  the  process,  it 
replaces  the  CLLI  codes  of  the  endpoint  switches  with  index  numbers  into 
the  switch  list.  This  step  optimizes  future  processing  tasks.  The  output  file  is 
a  combined  and  indexed  trunk  group/path  file,  given  a  user-specified  name. 


2.2  Generating  Damage  Vectors 

A  damage  vector  can  be  thought  of  as  one  random  instance,  or  scenario,  of  possible  network 
damage.  Given  the  probabilities  of  failure  of  each  network  component,  such  as  switches  and  spans 
(including  endpoint  nodes  such  as  repeaters),  it  is  possible  to  generate  many  different  damage  vectors, 
where  each  network  component  is  identified  as  being  in  either  the  damaged  or  undamaged  state.  Since 
each  damage  vector  is  based  on  a  common  set  of  probabilities,  they  will  all  tend  to  have  similar  average 
levels  of  damage.  However,  each  vector  represents  a  slightly  different,  random  outcome  that  could  occur. 

As  described  in  previous  TAMI  analyses  (References  2, 3, 5),  TAMI  uses  a  Monte  Carlo  approach, 
sampling  as  many  damage  vectors  as  needed  to  reach  a  suitable  confidence  level  in  overall  network 
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performance  results.  This  section  describes  the  two  modules,  damage  and  mklink,  that  generate  the  pool 
of  damage  vectors  from  which  the  modules  in  the  Monte  Carlo  loop  sample.  Damage  is  generic  to  both 
LEC  and  IEC  spans  and  nodes,  whereas  mklink  is  specific  to  lECs-it  maps  the  effect  of  damaged 
component  spans  and  nodes  to  the  long-haul  transmission  paths  in  these  networks.  While  the  specific 
version  of  damage  described  in  this  document  calculates  telecommunications  damage  due  to  EMP  and 
fallout  radiation,  future  versions  of  this  module  may  be  developed  to  characterize  damage  due  to  other 
threats,  such  as  earthquakes,  floods,  or  hurricanes. 

The  modules  damage  and  mklink  are  described  as  follows: 

damage:  This  module  generates  a  user-defined  number  of  randomly  sampled  damage 

vectors  for  two  general  categories  of  assets:  nodes  and  spans.  Damage  is 
based  on  the  susceptibility  of  each  equipment  type  to  EMP  or  fallout 
radiation.  Each  span  and  node  equipment  type  has  a  cumulative  distribution 
function  (CDF)  which  defines  the  equipment’s  probability  of  failure.  The  input 
span  or  node  files  must  have  a  field  describing  equipment  type.  In  the  output 
span  or  node  file,  this  field  will  be  replaced  with  the  string  of  damage  vectors- 
one  0  or  1  for  each  damage  vector  requested.  It  is  most  common  to  generate 
a  pool  of  15  damage  vectors  for  each  type  of  damage  (low,  medium,  and  high 
EMP  intensity). 

mklink:  The  mklink  module  generates  pools  of  damaged  IEC  paths  based  on  the 

component  span  and  node  damage  files  produced  by  damage.  It  uses  the 
combined  trunk/path  file  and  the  span  and  node  damage  files  as  input.  It 
steps  through  the  endpoint  nodes  and  the  chain  of  spans  that  make  up  each 
path,  checking  each  component  to  determine  if  the  overall  path  is  damaged 
or  surviving.  The  path’s  list  of  spans  are  replaced  by  the  string  of  damage 
vectors  in  the  output  file. 
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3.0  Module  Descriptions 


This  section  describes  the  first  1 1  TAMI  modules.  Overall  documentation  is  provided  for  each  module, 
followed  by  detailed  documentation  of  each  component  function.  Secion  3.1  describes  the 
documentation  conventions  used  in  the  sections  that  follow.  Many  of  these  conventions  were  adopted  to 
make  the  documentation  independent  of  the  details  of  ‘C’  syntax 
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3.1  Documentation  Conventions 


This  manual  documents  modules  and  functions  coded  in  the  ‘C’  programming  language.  Throughout  the 
manual  certain  conventions  which  may  differ  slightly  from  standard  ‘C’  terminology  have  been  adopted  in 
order  to  more  clearly  describe  data  types,  inputs,  outputs,  includes  and  file  types .  In  addition  the 
courier  font  is  used  to  denote  module  elements  such  as  variable  names,  file  names,  call  syntax,  etc.... 


Variable  names  are  defined  by  the  following  conventions; 


Convention 

Example 

Definition 

character 

C 

The  standard  ‘C’  data  type  char 

integer 

i 

The  standard  ‘C’  data  type  int 

float 

real 

The  standard  ‘C’  data  type  float 

long  integer 

pos 

The  standard  ‘C’  data  type  long 

file 

outfile 

The  standard  ‘C’  data  type  FILE,  a 
pointer  to  a  file  string 

extern 

optarg 

The  standard  ‘C’  data  type 
modifier  extern  indicating  the 
variable  is  declared  outside  the 
module  (e.g.,  the  operating 
system) 

global 

idx_num 

Variables  that  are  declared 
globally  accessible  from  any 
function 

double 

supp_cdf_table [ ] [] 

The  standard  ‘C  double 
precision  float  data  type 

pointer 

*varname 

Denotes  a  pointer  to  any  variable, 
varname 

Constants 

PATH__REC 

The  standard  ‘C’  ffdefine 

structure 

p_struct  p[] 

The  standard  ‘C’  aggregate, 

with  field 

heterogeneous  hierarchical  data 

integer  p  [  ] .  three 

structure  composed  of  a  main 
variable  name  and  sub  fields  of 
multiple  data  types 

Inputs/Outputs  are  defined  by  the  following  conventions: 

Inputs  are  of  two  types:  1)  formal  inputs  are  passed  in  by  the  calling  function;  2)  global  inputs  are  variables 
as  defined  above. 

Outputs  are  of  three  types:  1)  the  formal  parameter  is  returned  tby  he  called  function;  2)  arguments  that 
are  passed  by  reference  are  modified;  3)  global  outputs  are  variables  as  defined  above 

Includes  are  defined  by  the  following  conventions: 

Includes  are  of  two  types:  1 )  Standard  ‘C’  defined  function  sets,  e.g.,  <stdio .  c>;  and  2)  user  defined 
function  sets,  e.g.,  " f  ileio .  c"  (see  Appendix  B) 

File  formats  are  defined  by  the  following  conventions: 

1)  <CLLIA>,  <CLLIZ>,  <size> 

2)  (ell,  lx,  cl  1 ,  lx,  i6) 

Linel  shows  the  names  and  relative  positions  of  the  fields  within  each  record.  Line  2  shows  the  data  type 
and  length  of  each  field,  where: 

ocharacter 

x=space 

Mnteger 
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f=float 


Placement  of  algorithm  and  variables  local  to  main() : 

Module  level  descriptions  are  inclusive  of  the  algorithms  and  variables  local  to  the  function  main( )  for 
each  module 

Equality  of  trunk  group  and  circuit  group 

Throughout  this  document  the  terms  trunk  group  and  circuit  group  are  used  interchangeably 
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3.2  cg_make:  Make  Circuit  Groups  Module 


Purpose  This  module  uses  the  eg  and  node  ICF  data  files  to  produce  a  trunk  group  formatted  for 
use  with  other  TAMI  modules. 

Call  Syntax  cg_make 
Input 

Files  ICF  node  file  This  file  name  is  hard-coded  to  node_dat.icf.  See  the  ICF  file 

description  in  Appendix  A  for  more  information  regarding  contents 
and  format. 

ICF  eg  file  This  file  name  is  hard-coded  to  ‘cg_dat.icf.’  See  the  ICF  file 

description  in  Appendix  A  for  more  information  regarding  contents 
and  format. 

Output 
Files 


format  <CLLI  A>,  <CLLI  Z>,  <trunk_size> 

(ell,  lx,  ell,  lx,  i6) 

example  ADMSTX0101T  AKRNOH2505T  120 

Includes  <stdio.h> 

<string.h> 

"  ic f .  hi "  Defines  constants  used  to  process  ICF  files 

"  f  ileio .  c *  User-defined  I/O  functions;  see  Appendix  B 

Constants  Constants  used  in  array_make  are  defined  in  "icf  .hi"  as  follows: 

node_max  64  number  of  characters  in  a  ICF  node  file  record 

cg_max  3  8  number  of  characters  in  a  ICF  eg  file  record 

Global 

Variables  none 
Local 

Variables  Variables  local  to  main  () :  none. 

Component 

Functions  make_cgs  ( )  builds  output  trunk  group  records  by  looping  through  each 

record  in  the  eg  file 

node_f  ind  ( )  returns  the  CLLI  code  for  a  given  node  index 

f  get  ( )  user  defined  utility  I/O  function;  see  Appendix  B 


trunk  size  file  This  file  contains  a  list  of  trunks.  Each  line  contains  two  11 -character 
CLLI  codes  (the  two  span  endpoints),  along  with  an  associated  trunk 
size . 
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Function 

Tree 


Algorithmic 

Description 


main  ( )  —  make_cgs  ( ) 


fget() 

node_f ind ( )  —  f get ( ) 


The  purpose  of  this  module  is  to  produce  a  trunk  group  file  formatted  for  input  to  other 
TAMI  modules.  Cg_make  ( )  performs  this  task  by  replacing  the  node  index  numbers  in 
the  eg  records  with  the  node  CLLI  codes  and  printing  out  these  endpoints  along  with  a 
trunk  group  quantity.. 

This  module  consists  of  a  call  to  the  make_cgs  ( )  function,  which  reads  in  the  input 
files,  performs  the  amin  algorithm  and  writes  the  output  trunk  group  file. 
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3.2.1  make_cgs 


function 


cg_make  module 


Inputs 

Outputs 

file 

returns 

Purpose 

Called  By 

Calls  To 

Local 

Variables 

file 

integer 


character 

Global 

Variables 

Algorithmic 

Description 


none;  operates  on  global  variables 


*writef  ile  pointer  to  the  output  trunk  group,  hardcoded  to 

' cg_make . out ' 


none 

This  function  reformats  information  from  the  ICF  node  and  eg  files  to  create  the  output 
trunk  size  file. 

main ( ) 

make_link ( ) ,  f get ( ) 


*nodefile,  *cgfile 

pointers  to  the  input  ICF  node  and  eg  data  files 
*writef  ile  pointer  to  the  output  trunk  size  file 


no_nodes 

idx_num 

file_pos 

status 

no_cgs 

nodeAidx 

nodeZidx 

ntrkqty 


the  number  of  records  in  the  ICF  node  file 

loop  count  variable  for  each  eg  record 

pointer  to  a  particular  byte  or  position  in  the  ICF  eg  file 

not  used 

the  number  of  records  in  the  ICF  eg  file 
the  node  index  of  the  originating  circuit  group  endpoint 
the  node  index  of  the  terminating  circuit  group  endpoint 
the  quantitiy  of  trunks  in  a  circuit  group  record 


clli_A [  ]  used  to  hold  the  originating  node  CLLI  code 

clli_z  [  ]  used  to  hold  the  terminating  node  CLLI  code 

node_info  [  ]  used  to  hold  a  line/record  from  the  ICF  node  file 

cg_info  [  ]  used  to  hold  a  line/record  from  the  ICF  eg  file 


none 


The  function  begins  by  opening  the  input  and  output  files  and  counting  the  number  of 
records  in  the  eg  file.  For  each  record  in  the  ICF  circuit  group  file,  this  function  parses 
the  circuit  group  endpoints  (denoted  by  node  indexex)  and  the  circuit  group  quantity 
fields.  For  the  node  index  endpoints,  node_f  ind  ( )  is  called,  which  returns  the  node 
CLLI  code.  Make_cgs  ( )  writes  the  CLLI  code  endpoints  and  trunk  group  size  to  the 
output  file.  When  each  input  CG  file  record  has  been  reformatted,  the  function  returns. 
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3.2.2  node_find 


function 


cg_make  module 


Inputs 

integer 

file 

Outputs 

character 

returns 

Purpose 

Called  By 

Calls  To 

Local 

Variables 

character 

long 

Global 

Variables 

Global 

Constants 

Algorithmic 

Description 


idx_num  the  index  of  a  node  in  the  ICF  node  file 

*nodef  ile  the  file  pointer  to  the  ICF  node  file 

*clli_ptr  [  ]  a  pointer  to  a  string  in  which  a  node  CLLI  code  is  returned 

not  used 

Given  a  node  index,  this  function  returns  the  node  CLLI  code 

make_cgs ( ) 
f get ( ) 

node_info  [  ]  array  to  hold  node  data 

clli_temp  [  ]  array  to  temporarily  hold  a  CLLI  code 
f  iie_pos  position  in  the  ICF  node  file 


none 


node_max  the  number  of  characters  in  a  node  file  record 


Given  a  node  index,  this  file  calculates  the  node  record’s  position  in  the  node  CLLI 
code. 

This  function  begins  by  using  the  node  index  to  calculate  the  node  record’s  position  in 
the  ICF  node  file  (an  extra  record  must  be  skipped  to  account  for  a  header  record). 
Then,  this  function  calls  f  get  ( )  in  order  to  read  node  record  from  the  nodefile  into  the 
buffer  node_info  [  ] .  The  node  CLLI  code  field  is  then  parsed  and  checked  to  make 
sure  it  is  not  a  dummy  code  (all  X’s:  "xxxxxxxxxxx").  If  the  CLLI  code  is  valid,  it  is 
assigned  to  cili_ptr  to  be  returned  to  the  calling  function 
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3.3  span_make:  Make  Spans  Module 


Purpose  This  module  decodes  span  information  from  the  node  and  link  ICF  data  files;  the  span 
output  file  is  used  by  the  damage  module,  and  is  referenced  by  span  record  indices  in 
the  path  file. 

Call  Syntax  span_make 

Input 

Files  ICF  node  file  This  file  name  is  hard-coded  to ‘node_dat.icf.’  See  the  ICF  file 

description  (Appendix  A)  for  more  information  regarding  contents 
and  format. 

ICF  link  file  This  file  name  is  hard-coded  to  ‘link_dat.icf.’  See  the  ICF  file 

description  (Appendix  A)  for  more  information  regarding  contents 
and  format. 

Output 

Files  span  file  This  file  contains  a  list  of  spans.  Each  line  contains  two  1 1  -character 

CLLI  codes  (the  two  span  endpoints),  a  2-character  equipment  code, 
and  Vertical-Horizontal  coordinates  for  each  endpoint. 

format  <CLLI  A>,  <CLLI  Z>,  equipment  code>,  <V-coord  A>,  <H-coord  A>, 
<V-coord  Z>,  <H-coord  Z> 

(ell,  lx,  ell,  lx,  c2,  lx,  i5,  lx,  i5,  lx,  i5,  lx,  i5) 

Includes  <stdio.h> 

"  ic f .  hi "  Defines  constants  used  to  process  ICF  files 

"fileio .  c"  User-defined  I/O  functions;  see  Appendix  B 

Constants  Constants  used  in  span_make  are  defined  in  "icf  .hi"  as  follows: 

node_max  64  number  of  characters  in  a  ICF  node  file  record 

Node_idx_f  ldlen  4  number  of  characters  in  the  node  index  field  of  the  ICF  node  file 

link_max  2 4  number  of  characters  in  a  ICF  link  file  record 

clli_size  12  number  of  characters  in  a  CLLI  code  (11)  plus  the  standard  ‘C’  null 

character 

Global 

Variables  none 
Local 

Variables  Variables  local  to  main( ) :  none. 

Component 

Functions  make_spans  ( )  loops  through  the  node  file  to  build  the  data  records 

make_link  ( )  for  a  given  node,  makes  a  record  for  each  node  link,  given  in 

the  link  file 

node_f  ind  ( )  finds  the  corresponding  node  index  in  the  link  file  for  each 

node  index  in  the  node  file 
return_type  ( )  reclassifies  equipment  type 

f  get  ( )  reads  in  a  given  number  of  bytes  from  a  given  file  position 
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Function 

Tree 


Algorithmic 

Description 


main  ( )  — make_spans  ( )  -i —  f get  ( ) 

|—  make„link  ( ) 


f get { ) 

node_f ind { )  —  f get { ) 
return_type { ) 


The  purpose  of  this  module  is  to  decode  span  information  from  the  node  and  link  1CF  data 
files.  Span/link  records  are  the  shortest  identifiable  segments  of  telecommunications 
transmission  networks,  typically  representing  segments  between  repeaters,  or  between  a 
repeater  and  multiplexing/switching  equipment.  The  span_make  module  outputs  a  list  of 
these  spans,  designated  by  the  node  indices  of  the  two  span  endpoints,  along  with 
corresponding  equipment  types  and  vertical/horizontal  coordinates. 

This  module  uses  the  span_make  ( )  function  to  open  the  input/output  file,  and  to 
control  the  building  of  the  records  to  be  written  to  the  output  file.  It  then  calls 
make_link  ( )  (which  in  turn  calls  node_f  ind  ( )  to  set  an  index  between  the  node  and 
link  files,  and  return_type  ( )  to  reclassify  equipment  types).  Make_link  ( ) , 
assembles  the  completed  records,  and  writes  them  to  the  output  file. 
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3.3.1  make_spans 


function 


span_make  module 


Inputs  none 
Outputs 

file  *writefile  pointer  to  the  output  span  file 

returns  integer  number  of  nodes  in  ICF  node  file  for  which  links  have  been  processed  in 

the  ICF  link  file 


Purpose  For  each  record  in  the  ICF  node  file,  this  function  builds  the  spans  that  terminate  at  that 
node  from  information  contained  in  the  ICF  link  file,  and  builds  records  with  these  spans 
and  their  associated  equipment  codes  and  vertical/horizontal  coordinates, . 

Called  By  main  ( ) 

Calls  To  make_link  ( ) ,  fget  ( ) 

Local 

Variables 


file 


*nodefile,  *linkfile 

pointers  to  the  input  node  and  link  ICF  data  files 
*writef  ile  pointer  to  combined  node/link/equipment  code  output  file 


integer  link_head 
link_tail 
no_nodes 
idx_num 
f ile_pos 
status 
v_temp 
h_temp 


reference  to  the  beginning  of  a  node’s  ICF  link  file  references 
reference  to  the  end  of  a  node’s  ICF  link  file  references 
the  number  of  records  in  the  ICF  node  file 
general  loop  count  variable 

pointer  to  a  particular  byte  or  position  in  the  ICF  node  file 
non-zero  if  the  function’s  call  to  make_link  ( )  was  successful 
temporarily  holds  the  vertical  coordinate  of  the  current  node 
temporarily  holds  the  horizontal  coordinate  of  the  current  node 


character  c  1 1  i_temp  [  ] 

node_inf o [ ] 


used  to  hold  a  node  CLLI  code 

used  to  hold  a  line/record  from  the  ICF  node  file 


Global 

Variables  file  node_dat.icf 
link_dat . icf 


Algorithmic 

Description  This  function  processes  the  ICF  node  file,  record  by  record.  For  each  node  record,  it 
parses  the  node  CLLI  code  field  and  makes  sure  it  is  not  a  dummy  code  (all  X’s: 
"xxxxxxxxxxx").  Then  it  parses  the  iink_head  and  link_tail  fields  from  the 
node  record.  These  fields  point  to  the  node’s  corresponding  ICF  link  file  records.  If  the 
iink_head  and  iink_tail  fields  are  valid  (non-zero),  then  make_iink( )  is  called, 
which  actually  steps  through  each  of  the  node’s  link  records ,  reclassifies  equipment 
types,  captures  vertical  and  horizontal  coordinates  and  builds  the  spans.  If  the  call  to 
make_link  ( )  returns  a  status  of  o,  then  a  general  error  message  is  printed  to  the 
output  terminal. 
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3.3.2  makejink 


function 


span_make  module 


Inputs 

integer 

file 

character 

Outputs 

returns 

Purpose 

Called  By 

Calls  To 

Local 

Variables 

character 


long 

integer 


Global 

Variables 

Algorithmic 

Description 


head_pt 
tail_pt 
node_v 
node_h 
*link_file 
*node_f ile 
*outf ile 
node_clli [] 


the  pointer  to  the  first  link  file  record  describing  the  current  node’s  links 

the  pointer  to  the  last  link  file  record  describing  the  current  node’s  links 

vertical  coordinate  of  the  current  node 

horizontal  coordinate  of  the  current  node 

the  pointer  to  the  ICF  link  file 

the  pointer  to  the  ICF  node  file 

the  pointer  to  the  span  output  file 

the  current  node  CLLI  code 


integer  a  status  indicator,  equal  to  1  if  make_link  ( )  ran  without  error,  or  0  if  an 
error  occurred  in  make_link  ( ) 

Given  a  node  index  number  and  the  starting  and  ending  link  records  for  that  node,  this 
function  builds  the  spans  that  terminate  at  that  node  and  writes  them  to  the  output  file, 
along  with  the  span  equipment  type  and  V-H  coordinates  of  the  span  endpoints. 

make_spans ( ) 

f get ( ) ,  node_f ind ( ) ,  return_type ( ) 


1 inkrec  or d [ LINK_MAX+ 1 ] 
link_clli [ ] 

link_type [ ] 
type 


used  to  read  in  and  hold  a  record  from  the  link  file 
holds  the  CLLI  code  of  the  terminating  span 
endpoint 

holds  the  TAMI  span  equipment  type 
holds  the  ICF  span  equipment  type 


f_pos 


pointer  to  the  current  byte/position  in  the  ICF  link  file 


diff 


i 

j 

status 

link_v,  link_h 
node 


the  number  of  link  records  to  be  processed  for  a 
given  node,  equal  to  the  difference  between 
tail_pt  and  head_pt 
refers  to  a  position  in  linkrecord  [  ]  as  it  is 
sequentially  processed 

counts  the  number  of  link  records  processed,  up  to 

diff 

equal  to  1  if  make_link  ( )  ran  without  error,  0  if  an 
error  occurred 

the  V-H  coordinates  of  the  terminating  span 
endpoint 

the  index  of  a  span  endpoint  in  the  link  file 


none 


In  the  ICF  file  format,  a  node  file  record  points  to  the  range  of  link  file  records  that 
describes  the  other  endpoint  of  links  that  use  that  node  (see  Appendix  A).  Each  link 
file  record  has  fields  reserved  for  up  to  four  such  link  endpoints.  For  a  given  node, 
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starting  link  record,  and  ending  link  record,  function  make_link  { )  builds  each 
link/span  along  with  an  equipment  code,  and  V-H  coordinates  of  each  endpoint  and 
writes  this  data  to  the  output  file.  If  an  error  occurs,  make_link  ( )  returns  a  status  of  0. 

The  function  starts  by  calculating  dif  f ,  the  number  of  link  records  to  process  from 
head_pt  to  tail_pt.  It  then  enters  a  loop  to  read  each  of  the  dif  f  link  records  into 
linkrecordf]  to  reclassify  the  equipment  code,  to  look  up  the  CLLI  codes  and  V-H 
coordinates  of  the  span  endpoints  and  to  verify  that  no  file  read  error  occurred.  For 
each  link  record,  the  function  scans  link  endpoint  fields  until  all  four  link  endpoints  have 
been  processed  or  a  blank  field  is  encountered.  After  all  of  the  cuurent  node’s 
span/link  records  have  been  processed,  the  function  returns  the  value  of  status  to 
the  calling  routine. 
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3.3.3  node_find 


function 


span_make  module 


Inputs 

integer 

idx_num 

*vc 

*hc 

the  index  of  the  node  being  constructed  in  this  module 
pointer  to  the  vertical  coordinate  of  the  node 
pointer  the  horizontal  coordinate  of  the  node 

file 

*nodef ile 

the  file  pointer  to  the  ICF  nodefile 

character 

clli_temp [ ] 

temporarily  holds  the  CLLI  code 

Outputs 

returns 

no  formal  values  are  returned;  outputs  are  written  to  the  variable  address  for  the  vertical 
and  horizontal  coordinates 

Purpose 

To  look  up  a  node  by  index  and  return  the  CLLI  code  and  vertical  and  horizontal 
coordinates  and  node. 

Called  By 

make_link( ) 

Calls  To 

f get ( ) 

Local 

Variables 

character 

node_inf o [ ] 

string  to  hold  a  node  record 

long 

f  ile__pos 

position  in  the  ICF  node  file 

Global 

Variables 

none 

Global 

Constants 

NODE_MAX 

number  of  characters  in  an  ICF  node  file  record 

Algorithmic 

Description 

This  function  is  called  by  mk_iink  ( )  to  process  the  nodefile,  line  by  line,  to  capture 
the  vertical  and  horizontal  coordinates  of  each  CLLI  code.  First  this  function  sets  the  file 

pointer  to  the  second  line  of  the  file,  skipping  a  header  record.  Then,  this  function 
proceeds  to  call  f  get  ( )  in  order  to  read  the  bytes  of  data  that  contain  the  vertical  and 
horizontal  coordinates,  from  the  nodefile,  into  the  array  node_inf  o  ( ) .  Upon  return  to 
the  function,  an  end  of  line  character  is  written  to  the  array  record,  and  the  v  and  h 
coordinates  are  filtered  out  of  the  node_inf  o  ( )  record,  and  into  *vc ,  *hc . 

This  function  begins  by  using  the  node  index  to  calculate  the  node  record’s  position  in 
the  ICF  node  file  (an  extra  record  must  be  skipped  to  account  for  a  header  record). 
Then,  this  function  calls  f  get  ( )  in  order  to  read  node  record  from  the  nodefile  into  the 
buffer  node_inf  o  [  ] .  The  node  CLLI  code  field  is  then  parsed  and  checked  to  make 
sure  it  is  not  a  dummy  code  (all  X’s:  "xxxxxxxxxxx").  If  the  CLLI  code  is  valid,  it  is 
assigned  to  clli_ptr  and  the  fields  for  the  pointer  s  *vc  and  *hc  (the  vertical  and 
horizontal  coordinates  )  are  assigned  to  be  returned  to  the  calling  function 
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3.3.4  return_type 


function 


span_make  module 


Inputs 

character 

Outputs 

returns 

Purpose 

Called  By 

Calls  To 

Local 

Variables 

character 

Global 

Variables 

Algorithmic 

Description 


linktype  The  one-character  ICF  equipment  code  for  a  link/span  record,  denoting  a 
narrowly  defined  set:  (t,d,e,n,g,l,c,w,z,v,u,3,x,r,y,i)  . 

character  The  converted  TAMI  equipment  type  code  from  the  set: 

(T1 ,  L4,  FO,  MW) . 

This  function  is  used  to  convert  the  ICF  span/link  type  to  a  TAMI  span  type. 

make_link ( ) 
none 


returntype  [  ]  This  output  string  holds  the  transformed  input  value  for 
communication  equipment  code 


none 


This  function  is  used  to  convert  the  ICF  span/link  type  to  a  TAMI  span  type.  The 
function  is  passed  a  one-character  equipment  code  which  it  maps  to  a  TAMI  equipment 
code:  T1 ,  L4,  FO  (fiber  optic),  MW  (microwave).  See  Appendix  A  for  a  description  of  ICF 
link  type  codes.  The  function  returns  the  new  type  to  the  calling  function. 
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3.4  array_make:  Array  Make  Module 


Purpose  This  module  decodes  and  reformats  span  information  from  the  node  and  link  ICF  data 
files;  the  span  (“array”)  data  is  output  to  a  file  for  use  by  the  mk_ncam_path  module. 

Call  Syntax  array_make 

Input 

Files  ICF  node  file  This  file  name  is  hard-coded  to  ‘node_dat.icf.’  See  the  ICF  file 

description  in  Appendix  A  for  more  information  regarding  contents 
and  format. 

ICF  link  file  This  file  name  is  hard-coded  to  ‘link_dat.icf.’  See  the  ICF  file 

description  in  Appendix  A  for  more  information  regarding  contents 
and  format. 

Output 

Files  array  file  This  file  name  is  hard  coded  to  ‘array_make.out.’  It  is  a  binary  file  that 

contains  a  record  number  and  pair  of  node  index  numbers  for  each 
span/link  record  stored  in  the  link_info  [  ]  structure  and 
reformatted  from  the  ICF  data  files. 

format  binary  file,  not  viewable 

Includes  <stdio.h>  Standard ‘C’ input/output  functions 

"  icf .  hi "  Defines  constants  used  to  process  ICF  files 
" f  ileio .  c"  User-defined  I/O  functions;  see  Appendix  B 

Constants  Constants  used  in  array_make  are  defined  in  "icf. hi"  asfollows: 

node_max  6  4  number  of  characters  in  a  ICF  node  file  record 

Node_idx_f  ldlen  4  number  of  characters  in  the  node  index  field  of  the  ICF  node  file 

link_max  2  4  number  of  characters  in  a  ICF  link  file  record 

Global 

Variables 

file  *array_data_f  ile 

pointer  to  the  output  array  data  file 

integer  iink_num  counts  the  number  of  links  records  placed  into  the  array_inf  o  [  ] 

data  structure 

count  counts  the  number  of  records  read  from  the  ICF  link  file 

fp  indicates  the  current  file  position  when  writing  to  output  file 

i  general  loop  count  variable 

Structure  link_info  [12000]  of  type  link_array 
with  fields: 

integer  iink_inf  o  [  ] .  rec_no  holds  the  span  index  number 

character  iink_info  [  ] .  link_pair  holds  both  node  index  numbers  of  the 

span  endpoints,  treated  as  string 

example 
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Local 

Variables 

Component 

Functions 


Function 

Tree 


Algorithmic 

Description 


rec_no 

link__pair 

link_info [i] 

i 

"  2591  97" 

link_info [i+1] 

i+1 

■  2591  834" 

Variables  local  to  main  ( ) :  none. 


make_array { ) 
make_link ( ) 

fget { ) 


loops  through  the  node  file  to  build  the  array  data  structure 
for  a  given  node,  makes  an  array  record  for  each  of  the 
node’s  links  given  in  the  link  file 
reads  in  a  given  number  of  bytes  from  a  given  file  position 


{make_link  ( )  —  fget  ( ) 
fget ( ) 

The  purpose  of  this  module  is  to  decode  span  information  from  the  node  and  link  ICF 
data  files.  Span/link  records  are  the  shortest  identifiable  segments  of 
telecommunications  transmission  networks,  typically  representing  segments  between 
repeaters,  or  between  a  repeater  and  multiplexing/switching  equipment.  The 
array_make  module  outputs  a  list  of  these  spans,  designated  by  the  node  indices  of 
the  two  span  endpoints.  This  list  is  used  in  the  mk_ncam_path  module  to  represent 
long-haul  switch-to-switch  transmission  routes  as  a  series  of  component  spans. 

This  module  opens  the  hard-coded  output  file  name,  “array_make .  out.”  It  then  calls 
make_array  ( )  (which  in  turn  calls  make_link  ( ) )  to  populate  the  link_inf  o  [  ] 
structure  with  spans.  This  structure  is  then  written  in  binary  form  to  the  output  file,  the 
file  is  closed,  and  the  total  number  of  link/span  records  is  written  to  the  screen. 

The  following  figure  depicts  the  data  flow  performed  by  this  module.  For  further 
description  of  ICF  format,  refer  to  Appendix  A. 
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3.4.1  make_array 


function 


array_make  module 


Inputs 

Outputs 

global 

returns 

Purpose 

Called  By 

Calls  To 

Local 

Variables 

file 

integer 

character 

Global 

Variables 

Algorithmic 

Description 


none;  operates  on  global  variables 

link_info  [12000]  Structure  Of  type  link_array 
with  fields: 

integer  iink_inf  o  [  ] .  rec_no  holds  the  span  index  number 

character  iink_inf  o  [  ] .  iink_pair  holds  both  node  index  numbers  of  the 

span  endpoints,  treated  as  string 

integer  number  of  nodes  in  ICF  node  file  for  which  links  have  been  processed  in 
the  ICF  link  file 

For  each  record  in  the  ICF  node  file,  this  function  builds  the  spans  that  terminate  at  that 
node  from  information  contained  in  the  ICF  link  file.  These  spans  are  stored  in  the 
iink_info[]  structure. 

main ( ) 

make_link ( ) ,  f get ( ) 


*nodefile,  *linkfile 

pointers  to  the  input  node  and  link  ICF  data  files 


1 ink_head 

link_tail 

no_nodes 

idx_num 

f ile_pos 

status 


reference  to  the  beginning  of  a  node’s  ICF  link  file  references 
reference  to  the  end  of  a  node’s  ICF  link  file  references 
the  number  of  records  in  the  ICF  node  file 
general  loop  count  variable 

pointer  to  a  particular  byte  or  position  in  the  ICF  node  file 
non-zero  if  the  function’s  call  to  make_link  ( )  was  successful 


clli_temp  [  ]  used  to  hold  a  node  CLLI  code 

node_info  [  ]  used  to  hold  a  line/record  from  the  ICF  node  file 


none 


This  function  processes  the  ICF  node  file,  record  by  record.  For  each  node  record,  it 
parses  the  node  CLLI  code  field  and  makes  sure  it  is  not  a  dummy  code  (all  X’s: 
"xxxxxxxxxxx").  Then  it  parses  the  link_head  and  iink_taii  fields  from  the 
node  record.  These  fields  point  to  the  node’s  corresponding  ICF  link  file  records.  If  the 
iink_head  and  link_taii  fields  are  valid  (non-zero),  then  make_link  ( )  is  called, 
which  actually  steps  through  each  of  the  node’s  link  records  and  builds  the  spans.  If  the 
call  to  make_iink( )  returns  a  status  of  o,  then  a  general  error  message  is  printed  to 
the  output  terminal.  Although  make_array  ( )  returns  the  number  of  records 
processed  in  the  node  file,  this  value  is  never  used  by  the  calling  routine. 
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3.4.2  make_link 


function 


array_make  module 


Inputs 

integer 


file 

Outputs 

global 


returns 

Purpose 

Called  By 

Calls  To 

Local 

Variables 

character 

long 

integer 


Global 

Variables 

Algorithmic 

Description 


node_idx 
head_pt 
tail_pt 
*link_f ile 


the  node  file  index  of  the  current  node  being  processed 
the  pointer  to  the  first  link  file  record  describing  the  current  node’s  links 
the  pointer  to  the  last  link  file  record  describing  the  current  node’s  links 
the  pointer  to  the  link  file 


link_info  [12000]  Structure  Of  type  link_array 
with  fields: 

integer  link_info[]  .rec_no  holds  the  span  index  number 
character  iink_inf  o  [  ] .  iink_pair  holds  both  node  index  numbers  of  the 

span  endpoints,  treated  as  string 

integer  link_num  the  number  of  records  in  iink_info  [];  also  points  to 

the  next  unused  link_inf  o  [  ]  record 

integer  a  status  indicator,  equal  to  1  if  make_iink  ( )  ran  without  error,  or  0  if  an 
error  occurred  in  make_link  ( ) 

Given  a  node  index  number  and  the  starting  and  ending  link  records  for  that  node,  this 
function  builds  the  spans  that  terminate  at  that  node  and  places  them  in  the 
iink_inf o  [  ]  structure. 

make_array ( ) 
f get ( ) 


linkrecord  [link_max+1  ]  used  to  read  in  and  hold  a  record  from  the  link  file 

l inkpair  [10]  temporarily  holds  a  pair  of  concatenated  node  index 

endpoints  that  define  a  link 

f _ pos  pointer  to  the  current  byte/position  in  the  ICF  link  file 


link_icbc 

diff 

i 

j 

status 


the  index  of  a  link  endpoint  in  the  link  file 

the  number  of  link  records  to  be  processed  for  a  given  node,  equal  to 

the  difference  between  tail_pt  and  head _pt 

refers  to  a  position  in  linkrecord  [  ]  as  it  is  sequentially  processed 

counts  the  number  of  link  records  processed,  up  to  diff 

equal  to  1  if  make_iink  ( )  ran  without  error,  0  if  an  error  occurred 


see  Outputs  above. 


In  the  ICF  file  format,  a  node  file  record  points  to  the  range  of  link  file  records  that 
describes  the  other  endpoint  of  links  that  use  that  node.  Each  link  file  record  has  fields 
reserved  for  up  to  four  such  link  endpoints.  For  a  given  node,  starting  link  record,  and 
ending  link  record,  function  make_link( )  builds  each  link/span  and  stores  it  in  the 
iink_info  [  ]  structure.  If  an  error  occurs,  make_iink  ( )  returns  a  status  of  0. 
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The  function  starts  by  calculating  dif  f ,  the  number  of  link  records  to  process  from 
head_pt  to  taii_pt.  It  then  enters  a  loop  to  read  each  link  record  from  head_pt  to 
tail_pt  into  linkrecord  [  ] ,  and  to  verify  that  no  file  read  error  occurred.  For  each 
link  record,  the  function  scans  link  endpoint  fields  until  all  four  link  endpoints  have  been 
processed  or  a  blank  field  is  encountered.  Processing  of  each  link  endpoint,  stored  in 
link_idx,  entails  the  following: 

•  Concatenating  the  span  endpoints,  (node_idx,  iink_idx)  into  linkpair 

•  Assigning  the  current  span/link  index  (link_num)  to  the  rec_no  field  of  the 
span/link  record,  link_info  [link_num]  .rec_no 

•  Copying  linkpair  into  the  link_pair  field  of  the  span/link  record, 
link_info [link_num] ,link_pair 

•  Incrementing  the  span/link  counter,  link_num 

•  Moving  i  to  point  to  the  next  link  field  in  the  linkrecord  [  ]  (points  to  the 
end  of  the  string  if  done) 

After  each  link  field  of  each  link  record  has  been  processed,  and  the  resulting  spans 
stored  in  iink_info  [  ] ,  make_link  ( )  returns  the  value  status  to  the  calling 
function. 
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3.5  mk_ncam_path:  Make  Paths  Module 


Purpose  This  module  decodes  and  reformats  path  information  from  the  ICF  data  files  and  the 
output  array  file  from  the  array_make  module;  whereas  the  ICF  files  encode  physical 
transmission  paths  as  a  series  of  indexed  nodes,  TAMI  must  use  paths  that  are 
encoded  as  a  series  of  spans,  where  each  span  has  a  characteristic  span  type  that  can 
be  damaged.  Mk_ncam_path  employs  code  and  data  types  from  the  IDA/CAM  code 
library.  Readers  are  directed  to  Reference  4,  the  IDA/CAM  Programmer’s  Manual  where 
appropriate. 

Call  Syntax  mk_ncam_path 

Input 
Files 


ICF  link  file  This  file  name  is  hard-coded  to  ‘link_dat.icf.’  See  the  ICF  file 

description  in  Appendix  A  for  more  information  regarding  contents 
and  format. 

>F  trunk  file  This  file  name  is  hard-coded  to  ‘cg_dat.icf.’  See  the  ICF  file 

description  in  Appendix  A  for  more  information  regarding  contents 
and  format. 


This  file  name  is  hard-coded  to  ‘node_dat.icf.’  See  the  ICF  file 
description  in  Appendix  A  for  more  information  regarding  contents 
and  format. 


This  file  name  is  hard-coded  to  ‘pid_dat.icf.’  See  the  ICF  file 
description  in  Appendix  A  for  more  information  regarding  contents 
and  format. 


array  file  This  file  name  is  hard  coded  to  ‘array_make.out.’  It  is  a  binary  file  that 
contains  a  record  number  and  pair  of  node  index  numbers  for  each 
span/link  record  stored  in  the  link_inf  o  [  ]  structure  and 
reformatted  from  the  ICF  data  files. 


format  binary  file,  not  viewable 

Output 

Files  path  file  This  file  name  is  hard  coded  to  ‘mk_ncam_path.out.’  Each  record  in 

this  file  specifies  a  physical  transmission  path  between  a  pair  of 
switches.  A  physical  transmission  path  is  defined  by  the  series  of 
spans  (from  none  for  collocated  switches  to  a  maximum  of  662)  that 
connect  a  switch  pair.  Spans  are  identified  by  indexes  that  point  to 
the  appropriate  record  number  in  the  span  file. 

format  <switch  CLLI  A>,  <switch  CLLI  Z>,  <span1>,  <span2>, ... ,  <span  n> 
(ell,  lx,  ell,  lx,  i6,  i6, ... ,  i6) 

example  ADMSTX0101T  AKRNOH2505T  3045  3042  7579  237 

(where '3045  .  .  .'  are  record  numbers  in  the  span  file  output 
by  the  span_make  module) 


Includes  "nat.h"  I DA/CA  M  include  file  (Reference  4) 

Constants  None 
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Global 

Variables 

cg_path 

*f irst_cg 

points  to  the  first  eg  in  the  eg  structure  defined  in  Reference  4;  uses 
user-defined  type 

integer 

count 

first_f lag 
err 

counts  the  number  of  records  in  the  array  input  file 

indicates  whether  the  first  path  of  a  trunk  group  is  being  processed 

toggle  to  indicate  error  in  command  line  arguments 

structure 

link_info [12000]  of  type  link_array 
with  fields: 

integer  link_inf o  [  ] .  rec_no  holds  the  span  index  number 

string  link_inf o  [  ] .  iink_pair  holds  both  node  index  numbers  of  the 

span  endpoints,  treated  as  string 

Local 

Variables  Variables  local  to  main  ( ) : 


character  c  a  single  character  used  to  parse  command  line  options 

external  *optarg 

points  to  the  command  line  argument  string  supplied  externally  by  the 
operating  system 

cg_path  *cg_node  points  to  a  record  in  the  eg  structure  defined  in  Reference  4;  uses  user- 

defined  type 

int  i  general  loop  count  variable 

external  *optind 

points  to  the  number  of  command  line  arguments  processed,  supplied 
externally  by  the  operating  system 

file  *array_data_file,  *outfile 

pointers  to  the  input  array  file  and  output  path  file 


Component 

Functions 


write_span( ) 

writes  out  the  path,  including  all  the  spans,  for  a  given  circuit 
group  record 

bsearch ( ) 

standard  ‘C’  binary  search  routine,  used  to  search  for  spans 
in  the  iink_info  [  ]  structure 

qsort ( ) 

standard  ‘C’  sort  routine,  used  to  sort  iink_info  [  ] 

span_cmp ( ) 

string  comparison  function  used  by  bsearch  ( ) ;  see 
char_comp  ( )  in  Appendix  B  for  description 

sort_cmp ( ) 

string  comparison  function  used  by  qsort  ( ) ;  see 
char_comp  ( )  in  Appendix  B  for  description 

get__data  ( ) 

this  IDA/CAM  routine  loads  all  four  ICF  files  into  the  global 
IDA/CAM  data  structures  defined  in  "nat .  h .  *  See 
Reference  4  for  a  description  of  this  function 
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Function 

Tree 


Algorithmic 

Description 


r-  get_data  ( ) 

main  ( )  — J-  qsort  { )  —  sort_cmp  ( ) 

L  write_span  ( )  —  bsearch  ( )  —  span__cmp  ( ) 


As  described  in  Appendix  A,  the  ICF  paths  are  encoded  as  a  series  of  network  nodes. 
TAMI  requires  that  paths  be  described  as  series  of  links/spans.  This  module  uses  the 
list  of  spans  created  by  the  array_make  module  to  convert  ICF  paths  to  TAMI  paths 
and  replaces  indexed  nodes  with  their  CLLI  codes. 

The  module  starts  by  loading  the  input  files  into  structures.  First,  it  opens  the  file 
array_make .  out  and  loads  its  records  into  the  link_inf  o  [  ]  structure.  This 
structure  is  then  sorted  by  qsort  ( ) .  The  IDA/CAM  routine,  get_data  ( )  is  called  to 
load  the  four  ICF  files  into  data  structures. 

The  main  algorithm  is  then  performed  using  the  linked  list  of  circuit  group  data 
structures.  Each  of  these  structures  contains  a  pointer  to  the  linked  list  of  all  the  paths 
used  by  the  circuit  group.  Each  path  structure  points  to  the  linked  list  of  all  the  nodes 
that  form  the  path.  All  of  these  structures  are  defined  in  more  detail  in  Reference  4. 
Mk_ncam_path  steps  through  the  linked  list  of  circuit  groups,  calling  write_span  ( ) 
to  build  and  output  the  circuit  group’s  paths  in  TAMI  format. 
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mk_ncam_path  module 


write_span 

Inputs 

file 

cg_path 

Outputs 

Purpose 

Called  By 

Calls  To 

Local 

Variables 

pid_tbl 

path_node_tbl 

link_array 

integer 

character 

Global 

Variables 

integer 

Algorithmic 

Description 


function 


*  file  points  to  the  output  path  file 

*node  points  to  the  circuit  group  structure  for  which  paths  are  to  be  built; 
cg_path  is  a  user-defined  structure  described  in  Reference  4 

none;  prints  results  directly  to  output  file 

For  each  circuit  group  record  in  the  ICF  eg  file,  this  function  uses  TAMI  spans  stored  in 
the  link_info  [  ]  structure  to  build  the  paths  used  by  the  circuit  group. 

main ( ) 

bsearch ( ) 


*node_pid  pointer  to  a  table  of  a  paths  for  a  given  circuit  group;  pid_tbl  type 
defined  in  Reference  4 

*npath  pointer  to  a  particular  path;  path_node_tbl  type  defined  in 

Reference  4 

*span  pointer  to  an  element  of  the  iink_info  [  ]  structure 

indexl ,  index  2 

the  ICF  node  indexes  of  span  endpoints 
ent  counts  the  number  of  paths  processed  for  a  circuit  group 

cntl  counts  the  number  of  spans  processed  for  a  circuit  group 

buf  [  ]  holds  a  span  record  in  the  same  format  as 

link_info [ ] . link_pair 


f  irst_f  lag  indicates  whether  the  first  path  of  a  trunk  group  is  being  processed 

Contains  global  IDA/CAM  structures  declared  in  "nat  .h"  and  loaded  by 
get_data  ( ) ;  see  Reference  4 


For  each  circuit  group  record  in  the  ICF  eg  file,  this  function  uses  TAMI  spans  stored  in 
the  iink_inf  o  [  ]  structure  to  build  the  paths  used  by  the  circuit  group.  Specifically, 
write_span  ( )  performs  the  following  steps: 

1)  Uses  the  pointer  to  the  current  circuit  group,  *node,  to  access  the  path  endpoint 
CLLI  codes  and  a  pointer  to  the  cg’s  table  of  paths 

2)  Loops  through  each  path  in  the  path  table 

3)  For  each  path,  loops  through  all  the  nodes  that  compose  the  path,  searching 
link_info  [  ]  to  convert  each  chained  pair  of  nodes  into  a  link/span  index 

The  function  prints  its  results  to  the  output  file  as  they  are  obtained. 
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3.6  mat_trk:  Match  Trunks  module 


Purpose  For  every  pair  of  IEC  backbone  switches,  this  program  maps  the  logical  trunk  group  to 
the  corresponding  physical  transmission  paths,  as  described  in  Algorithmic  Description 
below.  Bi-directional  trunk  groups  are  the  default,  but  one-way  trunk  groups  are 
assumed  for  MCI. 


Call  Syntax 


mat_trk 

options : 
-a 
-d 
-f 

-m 

-o 


-f  <filename>  [ options ] 

turn  off  substitution  of  average  trunk  size 

turn  debug  mode  on  to  print  debug  statements 

reads  in  input  file  <f  iiename>  which  contains  a  list  of  the  5 

input/output  files  used  by  mat_trk 

specify  MCI  data,  which  expects  both  4  character  switch  CLLI  code 
and  a  3  character  location  code  in  the  switch  input  file 
assume  trunk  groups  are  one-way  (e.g.,  for  MCI) 
user  help-prints  call  syntax  and  exits  without  running 


example  mat_trk  -f  MCifiies .  fy94  -o  -m  -a  (spaces  optional) 


Input 

Files 


list  file  This  file  simply  contains  the  names  of  the  three  input  files  and  two 
output  files  to  be  used  by  mat_trk.  File  names  are  limited  by 
mat_trk  to  a  length  of  50  characters. 


format  linel : 
Iine2: 
Iine3: 
Iine4: 
Iine5: 


<path  file  name> 

<switch  file  name> 
ctrunk  file  name> 
coutput  trunk  file  name> 
coutput  path  file  name> 


switch  file  This  file  contains  the  list  of  IEC  backbone  switches.  For  MCI  data,  this 
file  also  contains  a  location  code  for  each  switch.  Non-MCI  switches 
are  specified  by  an  1 1 -character  CLLI  code,  where  the  first  8 
characters  identify  a  unique  location.  MCI  switches  are  specified  by  a 
4  character  code,  and  locations  are  given  by  a  separate  3  character 
code. 


format:  Non-MCI:  <IEC  switch  CLLI  code> 

(ell) 

MCI:  <MCI  switch  code>,  <MCI  location  code> 

(c4,  lx,  c3,  3x) 

input 

trunk  file  This  file,  created  by  the  cg_make  module,  specifies  the  trunk  groups 
and  quantities  for  the  IEC  backbone,  specified  by  the  end  point  CLLI 
codes  and  an  integer  number  of  trunks.  If  trunk  groups  are  assumed 
to  be  one-way,  then  the  first  CLLI  code  is  the  originating  switch. 

format:  <switch  CLLI  A>,  <switch  CLLI  Z>,  <trunk  quantity> 

(2x,  cl  1 ,  cl  1 ,  i4) 

path  file  Each  record  in  this  file,  created  by  the  mk_ncam_path  module, 

specifies  a  physical  transmission  path  between  a  pair  of  switches.  A 
physical  transmission  path  is  defined  by  the  series  of  spans  (from 
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Output 

Files 


Includes 

Constants 


Global 

Variables 

file 

integer 


none  for  collocated  switches  to  a  maximum  of  662)  that  connect  a 
switch  pair.  Spans  are  identified  by  indexes  that  point  to  the 
appropriate  record  number  in  the  span  file. 

format  <switch  CLLI  A>,  <switch  CLLI  Z>,  <span1>,  <span2> . <span  n> 

(cl  1 , 1  x,  cl  1 , 1  x,  i6,  i6 . i6) 


output  trunk  file  The  output  trunk  file  specifies  the  IEC  switch  CLLI  codes  of  the  trunk 
endpoints,  the  number  of  trunks  in  the  A  to  Z  direction  (or  all  bi¬ 
directional  trunks),  and  the  number  of  trunks  in  the  Z  to  A  direction 
(only  used  for  one-way  trunk  groups).  Each  record  is  in  1  -to-1 
correspondence  with  the  output  path  file.  That  is,  the  number  of 
trunks  in  the  n^  trunk  file  record  traverse  the  transmission  path 
specified  by  the  nth  path  file  record.  Therefore,  when  a  trunk  group 
is  split  over  5  paths  for  example,  there  will  be  5  trunk  file  records  to 
describe  this,  corresponding  to  each  of  the  5  path  file  records. 

format  <switch  CLLI  A>,  <switch  CLLI  Z>,  <A->Z  trunk  quantity;-,  <Z->A 
trunk  quantity> 

(ell,  lx,  ell,  lx,  i4,  lx,  i4) 


output  path  file  The  output  path  file  specifies  the  paths  used  to  implement  the  trunk 
groups.  If  a  path  has  no  corresponding  trunk  group  record,  then  the 
average  trunk  group  size  may  be  used,  or  the  path  record  can  be 
thrown  out.  There  are  two  differences  from  the  input  path  file:  (1)  if 
the  path  had  invalid  or  non-switch  endpoints  it  has  been  filtered  out; 
(2)  paths  that  could  not  be  matched  to  a  corresponding  trunk  group 
have  been  filtered  out  of  the  output  file  if  the  [  -a]  option  was  used. 

format  same  as  input  path  file 


<stdio .h> 

<stdlib.h> 

<string.h> 

"fileio.c"  See  Appendix  B 


PATH_REC  4000 
CLLI_LNG  12 
SWLOC_LNG  4 
SWITCH_MAX  200 
TRK_MAX  15000 


maximum  number  of  characters  in  a  path  file  record 

length  of  a  switch  CLLI  code,  including  terminating  null  character 

length  of  an  MCI  location  code,  including  terminating  null  character 

maximum  number  of  records  in  the  switch  file 

maximum  number  of  records  in  the  trunk  file 


*pathfile,  *switchfile,  *trunkfile,  *filelist,  *outfile, 
*outf  ile2  pointers  to  the  input  and  output  files 


tog_mci 

tog_spr 

tog_debug 

tog_noavg 

numswitch 

numtrunk 

maxnpath 


toggle  to  indicate  -m  command  line  option  is  being  used 

toggle  for  a  Sprint  option  that  is  no  longer  used 

toggle  to  indicate  -d  command  line  option  is  being  used 

toggle  to  indicate  -a  command  line  option  is  being  used 

the  number  of  records  read  in  from  the  switch  file 

the  number  of  validated  records  read  in  from  the  trunk  file 

indicates  the  maximum  number  of  path  file  records  that  pertain  to  a 

single  switch  pair 
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float 


avgtrunk 


the  average  size  of  the  valid  trunk  records 


character 


structure 


Component 

Functions 


Function 

Tree 


switches [SWITCH_MAX] [CLLI_LNG] 

array  to  hold  up  to  switch_max  I  EC  switch  CLLI  codes,  each  of 
length  clli_lng  (including  null  character) 

loc[SWITCH_MAX] [ SWLOC_LNG ] 

array  to  hold  up  to  switch_max  IEC  switch  location  codes  (used  only 
for  MCI  data),  each  of  length  swloc_lng  (including  null  character) 
maxAsw[CLLI_LNG] ,  maxZsw[CLLI_LNG] 

these  hold  the  CLLI  codes  of  the  switch  pair  with  the  maximum 
number  of  paths,  tracked  as  a  statistic  printed  to  the  screen 
buffer [100] [ PATH_REC ] 

this  buffer  holds  up  to  100  path  records  to  support  the  sequential 
processing  of  the  path  file 


trks [TRK_MAX]  of  type  trk_struct 
with  fields: 

character  trks[].clliA 

trks [ ] . clliZ 
integer  trks  [  ] .  qty 

trks [ ] .used 


originating  trunk  group  endpoint 
terminating  trunk  group  endpoint 
quantity  of  trunks  in  trunk  group  record 
toggle  to  track  use  of  trunk  group  record 


openfiles ( ) 
loadswitches ( ) 
loadtrunks ( ) 
outprint ( ) 
qsort ( ) 
bsearch ( ) 
char_comp ( ) 
processpaths ( ) 
getsize_oneway ( ) 
getsize ( ) 

getswidx ( ) 
processtrunks ( ) 


opens  input  and  output  files 

loads  switch  file  into  the  switch  list,  switches  [  ] 

loads  trunk  file  records  into  the  trunk  structure 

prints  out  one  output  trunk  file  record  for  each  path 

standard  ‘C’  quick  sort  routine,  used  to  sort  switch  list 

standard  ‘C’  binary  search  routine,  used  to  search  switch  list 

string  comparison  routine  for  qsort  ( )  and  bsearch  ( ) 

maps  a  logical  trunk  group  to  its  physical  paths 

finds  the  oneway  trunk  sizes  given  a  pair  of  switch  endpoints 

finds  the  bi-directional  trunk  size  given  a  pair  of  switch 

endpoints 

finds  the  index  number  of  a  switch  within  the  switch  list 
handles  trunk  groups  which  had  no  matching  paths 


P openfiles { ) 

1— loadswitches  ( )  - qsort  ()  —  char__comp  ( ) 


U  loadtrunks  ( )  -  bsearch  ( )  —  char_comp  ( ) 


main ( )  • 


I— processpaths ( ) 


—  bsearch  ( )  —  char_comp  ( ) 

—  getsize_oneway ( ) 

—  getsize () 

_  outprint ( ) 


L  processtrunks { )  — p  getswidx ( ) 

—  getsize_oneway ( ) 

—  outprint ( ) 
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Algorithmic 

Description  For  every  pair  of  IEC  backbone  switches,  this  module  maps  the  logical  trunk  group  to 
the  corresponding  physical  transmission  paths.  Because  the  trunk  group  and  path 
information  are  often  maintained  by  separate  units  within  a  carrier’s  organization,  there  is 
no  guarantee  that  the  logical  trunk  groups  map  cleanly  to  each  physical  path.  This 
module  addresses  this  problem  by  enforcing  a  number  of  “set  recombination”  rules: 

1 )  Invalid  endpoints.  T runk  groups  and  paths  that  do  not  have  switch  endpoints 
(identified  in  the  switch  file)  are  filtered  out  and  not  used 

2)  Paths  and  trunk  groups  match.  Where  paths  can  be  matched  to  a  corresponding 
trunk  group  (i.e.,  path  endpoints  are  the  same  as  trunk  group  endpoints),  the 
module  divides  the  trunks  in  the  trunk  group  equally  among  all  available  paths  (with 
any  integer  remainder  of  trunks  given  to  the  last  path).  This  is  the  most  reasonable 
assumption  in  the  absence  of  more  specific  carrier  data.  For  example,  a  trunk  group 
of  size  60  that  has  5  matching  physical  paths  would  be  divided  into  5  output  trunk 
group  records,  each  of  size  12. 

3)  Path,  but  no  trunk  group.  Where  a  path  cannot  be  matched  to  a  corresponding 
trunk  group,  the  module  gives  two  options.  One,  throw  the  path  out.  Or  two,  make 
up  a  trunk  group  containing  the  average  number  of  trunks  in  the  network,  based  on 
the  reasoning  that  a  trunk  group  should  exist  for  the  path,  but  was  inadvertently  left 
out  of  the  trunk  group  data.  The  first  option  is  usually  employed. 

4)  Trunk  group,  but  no  path.  Where  a  trunk  group  exists  with  no  corresponding 
physical  path  data,  the  program  checks  to  see  if  the  endpoints  are  collocated.  If  so, 
no  path  is  necessary  since  the  switches  are  in  the  same  building,  and  the  trunk 
group  size  can  be  used.  A  path  record  is  generated  (containing  no  spans)  to 
maintain  the  one-to-one  mapping  between  trunk  groups  and  paths.  If  the  switches 
are  not  collocated,  the  trunk  record  must  be  thrown  out  since  there  is  no 
corresponding  path  data  with  which  to  evaluate  network  damage. 

The  module  provides  the  option  [-o]  to  model  trunk  groups  as  one-way,  although 
paths  are  always  considered  to  be  bi-directional.  In  the  case  of  one-way  trunk  groups, 
the  module  maintains  separate  A— >Z  and  Z— >A  trunk  size  fields  for  each  switch  pair. 
One-way  trunk  groups  are  used  for  MCI  data.  The  module  also  provides  an  MCI  option 
[  -m]  to  indicate  that  the  switch  file  will  contain  4  character  switch  codes  and  3  character 
location  codes,  and  not  the  usual  1 1  character  CLLI  codes.  The  [  -a]  option  tells  the 
module  not  to  assume  an  average  trunk  size  for  paths  that  have  no  corresponding  trunk 
groups. 

After  the  command  line  arguments  have  been  parsed  and  interpreted,  main  ( ) 
executes  in  the  following  order: 

1)  Calls  openfiles  ( )  to  open  pointers  to  input  and  output  files 

2)  Calls  loadswitches  ( )  to  read  the  switch  file  into  switches  [  ] 

3)  Calls  loadtrunks  ( )  to  load  the  trunk  file  into  the  trunk  structure,  trks  [  ] .  Trunk 
records  with  non-switch  end  points  are  thrown  out 

4)  Calls  processpaths  ( )  to  sequentially  process  the  sorted  path  file  and  find 
matching  trunk  groups.  The  trks  [  ]  .  used  field  is  set  for  trunk  groups  that  are 
matched  here.  Output  paths  and  trunks  are  written  to  the  output  files  as  they  are 
matched 
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5)  Calls  processtrunks  ( )  to  handle  all  of  the  trunks  that  didn’t  have  matching  paths. 
If  the  endpoints  are  collocated,  it  uses  the  trunk  group;  otherwise,  it  must  be  thrown 
out 

6)  Prints  out  the  switch  pair  that  had  the  greatest  number  of  physical  paths,  then  exits. 
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3.6.1  openfiles 


function 


mat_trk  module 


Inputs 

character 


Outputs 

global 


returns 

Purpose 

Called  By 

Calls  To 

Local 

Variables 

character 

Global 

Variables 

Algorithmic 

Description 


files 


string  containing  the  name  of  the  file  that  lists  six  input/outout 
files 


*filelist 

*pathfile 

*switchfile 

*trunkfile 

*outfile 

*outfile2 

no  formal  values  are  returned 

To  open  path,  trunk  and  switch  input  files 

main ( ) 

none 


points  to  the  file  whose  name  is 
contained  in  the  files  string 
points  to  a  file  that  contains  information 
on  the  physical  paths  and  switches 
points  to  a  file  that  contains  information 
on  the  backbone  network  switches 
points  to  a  file  that  contains  information 
on  the  logical  trunks 
filtered  version  of  trunkfile 
filtered  version  of  pathfile 


and  path  and  trunk  output  files. 


tempfile  [50]  this  variable  is  used  temporarily  to  hold  the  name  of  the  next  file  to  be 
opened  and  read  in  from  the  list  of  files  in  filelist 


none 


This  function  opens  the  file  whose  name  is  stored  in  the  string  files,  setting  a 
filepointer  to  filelist .  Filelist  contains  a  list  of  all  the  input  files  to  be  opened 
in  the  following  order:  pathfile,  switchfile,  trunkfile,  outfile  and 
°utfiie2  This  function  then  proceeds  to  open  each  of  these  files,  in  the  order  they 
are  read  in  from  filelist,  assigning  them  to  the  matching  filepointers. 


Errors  encountered  during  any  file  opening  operation  result  in  an  error  message  beinq 
Panted  to  the  screen,  and  termination  of  the  module. 
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3.6.2  loadswitches 


function 


mat_trk  module 


Inputs  none;  operates  on  global  variables 

Outputs 

global  character  switches  [] 

loc  [  ] 

integer  numswitch 

file  *switchfile 

returns  no  formal  values  are  returned 

Purpose  To  read  from  the  switch  file,  to  load  the  switch  CLLI  codes  into  the  switches  vector,  to 
count  the  number  of  switch  records,  and  to  perform  an  alphabetical  sort 

Called  By  main ( ) 

Calls  To  qsort  ( )  the  quick  sort  routine  from  the  standard  ‘C’  library  stdiib . h 


Local 

Variables 

integer  k  general  loop  count  variable 

j  not  used 

character  lineU  used  to  hold  a  line  of  input  from  the  switch  file 

tempCLLi  [  ]  temporarily  holds  a  parsed  switch  name 
tempioc  [  ]  temporarily  holds  a  parsed  MCI  switch  location 

tempsw  [  ]  temporarily  holds  a  parsed  MCI  switch  CLLI  code 

Global 

Variables 

integer  tog_mci  a  toggle  used  to  indicate  that  MCI  switches  and  locations  should  be 

expected  in  switch  file 

Algorithmic 

Description  This  function  reads  the  switch  file  line  by  line,  loading  each  CLLI  code  into  the  array  of 
strings  switches  [  ] ,  and  setting  numswitch  to  the  total  number  of  switches  in  the 
switch  file.  Because  other  functions  in  this  module  depend  on  the  switches  being  in 
alphabetical  order,  the  routine  passes  the  switches  [  ]  array  to  qsort  ( ) . 

If  MCI  data  is  indicated  by  tog_mci,  then  each  switch  name  contains  a  four  character 
switch  CLLI  code  and  a  three  character  location  code.  In  this  case  the  function  loads 
the  CLLI  codes  into  switches ,  and  the  location  codes  into  loc  [  ] . 


the  list  of  IEC  switch  CLLI  codes 
the  list  of  MCI  switch  locations 
used  to  count  the  number  of  records  in 
the  switchfile 
points  to  the  switch  file 
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3.6.3  loadtrunks _ function  mat_trk  module 


Inputs  none;  operates  on  global  variables 

Outputs 

global  trk_struct  structure  trks  [  ] 
with  fields 

character  trksU.clliA 

trks [] .clliZ 

integer  trks  [  ]  .  qty 

trks [] .used 

returns  no  formal  values  are  returned 

Purpose  To  read  the  trunk  file,  loading  valid  records  into  the  trunk  structure  as  described  in  the 
algorithmic  description  below 

Called  By  main ( ) 

Calls  To  char_comp  ( )  the  function  used  to  specify  ascending  alphabetic  order  in  the 

character  comparison  performed  by  bsearch  ( ) 
bsearch  ( )  the  binary  search  routine  from  the  standard  ‘C’  library  stdlib.h 

Local 
Variables 

integer  k,  j 

*  f ound_A 

*  f ound_Z 
tottrunks 

Global 
Variables 

integer  numtrunk  the  number  of  valid  trunk  group  records  read  from  the  trunk  file 

float  avgtrunk  the  average  size  of  a  valid  trunk  group:  tottrunks /numtrunk 


Algorithmic 

Description 

This  function  handles  cases  where  a  trunk  group  record  did  not  have  a  corresponding 
physical  path .  If  the  trunk  group  endpoints  are  collocated,  then  a  physical  path  is 
unnecessaiy.  The  trunk  group  is  used  (written  to  the  output  trunk  file)  and  a 
corresponding  dummy  path  record  (path  with  no  span)  is  written  to  the  output  path  file 
to  maintain  the  required  one-to-one  mapping  between  logical  trunk  groups  and  physical 
paths.  Trunk  groups  that  do  not  have  collocated  endpoints  are  filtered  out  of  the  data 
and  are  not  used.  Because  these  trunk  groups  do  not  have  physical  path  information,  it 
is  impossible  to  evaluate  the  effect  of  network  damage  on  them.  The  function  logic  is  as 
follows. 

This  function  reads  the  trunk  file  line  by  line,  until  the  end  of  the  file  is  reached.  For 
each  line  (record),  it  parses  the  originating  trunk  end  point,  terminating  trunk  end  point, 
and  trunk  quantity,  and  loads  these  fields  into  the  trks  [  ]  structure.  Next,  the  function 
conducts  a  binary  search  to  check  that  the  trunk  end  points,  trks  [  ]  .  ciliA  and 
trks  [  ] .  ciliz,  are  found  in  the  list  of  switches,  switches  [  ] .  If  so,  the  trunk  record 
is  valid,  the  loop  counter  is  advanced,  and  the  trunk  quantity  is  summed  into 


general  loop  count  variables 

integer  pointer  used  to  indicate  whether  the  originating  end  point  of 
a  trunk  group  is  a  valid  switch:  zero  if  false  and  non-zero  if  true 
integer  pointer  used  to  indicate  whether  the  terminating  end  point  of 
a  trunk  group  is  a  valid  switch:  zero  if  false  and  non-zero  if  true 
total  number  of  trunks  for  the  I  EC  that  have  valid  switch  end  points 


used  to  hold  each  record  in  the  trunk  file 

originating  trunk  group  endpoint 
terminating  trunk  group  endpoint 
quantity  of  trunks  in  trunk  group  record 
toggle  to  track  use  of  trunk  group  record 
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tottrunks.  If  not,  the  trunk  record  is  not  valid  and  the  loop  counter  is  not  advanced, 
so  that  the  next  record  read  in  from  the  trunkfile  will  overwrite  it. 

When  the  end  of  the  file  is  reached,  numtrunk  is  set  to  the  loop  counter,  and  specifies 
the  number  of  valid  records  read.  Avgtrunk  is  computed  as  tottrunks /numtrunk, 
and  both  numtrunk  and  avgtrunk  are  printed  to  the  standard  output. 
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3.6.4  processpaths 


function 


mat_trk  module 


Inputs 

integer  tog_oneway  a  command  line  toggle  used  to  indicate  the  use  of  one  way 

trunks 

Outputs 

global  character  buffer  []  a  vector  of  strings  that  holds  valid  paths 

before  printing  them  to  an  outfile 
maxAsw  [  ]  used  to  hold  originating  endpoint 

maxZsw[  ]  used  to  hold  terminating  endpoint 

returns  no  formal  values  are  returned 

Purpose  To  process  paths  one  by  one  and  write  out  a  filtered  path  file  and  filtered  trunk  file  in 

one-to-one  correspondence  with  the  paths  as  described  in  the  algorithmic  description 
below 

Called  By  main  ( ) 

Calls  To  char_comp  ( )  the  function  used  to  specify  ascending  alphabetic  order 

in  the  character  comparison  performed  by  bsearch  ( ) 
bsearch  ( )  the  binary  search  routine  from  the  standard  ‘C’  library 

stdlib.h 

ge t s  i  z e_oneway  ( )  the  subroutine  used  to  determine  the  size  for  oneway 

trunks. 

outprint  ( )  This  routine  is  used  to  split  trunks  among  paths  and  print 

results  to  an  outfile 

getsize  ( )  the  subroutine  used  to  determine  the  size  for  bi¬ 

directional  trunks. 

Local 

Variables 

integer  k  general  loop  count  variable 

pathrec  counts  records  read  in  from  pathf  ile 

pathctr  counts  number  of  paths  for  a  given  switch  pair 

newpath  toggle  to  detect  next  switch  pair 

avgused  toggle  to  detect  use  of  average  trunk  size  constant  avgtrunk 

gtyA  trunk  size  variable  for  A->Z  direction 

qtyz  trunk  size  variable  for  Z->A  direction 

*  f  ound_A  integer  pointer  used  to  indicate  whether  the  originating  end  point  of 

a  trunk  group  is  a  valid  switch:  zero  if  false  and  non-zero  if  true 

*  f  ound_z  integer  pointer  used  to  indicate  whether  the  terminating  end  point  of 

a  trunk  group  is  a  valid  switch:  zero  if  false  and  non-zero  if  true 

character  pathl  ine  a  temporary  string  variable  to  hold  a  record  from  the  pathf  ile 
pathA  holds  the  originating  endpoint  of  the  path  in  pathline 

pathz  holds  the  terminating  endpoint  of  the  path  in  pathline 

nextA  holds  the  originating  endpoint  of  ‘next’  path  to  compare  it  with  current 

path 

nextz  holds  the  terminating  endpoint  of  ‘next’  path  to  compare  it  with 

current  path 
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Global 

Variables 

float  avgtrunk  the  average  size  of  a  valid  trunk  group:  to t trunks /numtrunk 

Algorithmic 

Description 

This  function  reads  the  first  record  of  the  path  file,  increments  the  path  record  counter,  pathrec , 
parses  the  originating  and  terminating  endpoints,  and  loads  these  into  pathA  and  pathz,  respectively. 
Next  the  function  conducts  a  binary  search  to  check  that  the  path  endpoints  are  found  in  the  list  of 
switches,  switches  [  ] .  If  so,  the  path  record  is  valid,  the  path  record  is  copied  to  buffer,  and  the  loop 
counter  is  advanced. 

Next  this  function  reads  the  remaining  records  in  the  path  file  line  by  line.  For  each  record  it 
parses  the  originating  and  terminating  endpoints  and  loads  them  into  nextA  and  nextz  respectively, 
then  a  comparison  is  made  between  this  pair  of  endpoints  and  pathA,  pathz.  If  the  endpoints  are  a 
match,  this  record  is  copied  to  buffer,  and  the  next  record  is  processed  in  the  same  manner.  (If  there  is 
not  a  match,  these  values  are  held  in  nextA,  nextz  for  the  next  iteration  of  this  section.)  When  all  sets 
of  matching  endpoints  have  been  found,  the  function  calls  a  subroutine,  (getsize_oneway  or 
getsize),  which  return  the  trunk  size  for  the  pathA,  pathz  switch  pair.  Then,  this  trunk  size  is  used  in  a 
call  to  the  outprint  subroutine,  to  divide  the  trunk  size  evenly  among  the  matching  sets  of  switch  pairs 
held  in  the  buffer,  with  any  remainder  going  to  the  last  switch  pair. 

Finally,  this  function  sets  nextA,  nextz,  the  last  read  in  switch  pair,  (which  were  also  the  first 
non-matching  pair)  equal  to  pathA,  pathz,  and  loops  back  to  searching  the  path  file  for  matching  pairs. 
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3.6.5  processtrunks  function 


mat_trk  module 


Inputs 

integer  tog_oneway  toggle  used  to  indicate  one-way  trunk  groups  for  MCI 


Outputs 


global  trk_struct  structure 
with  fields 

trks [ ] 

character 

trks [] .clliA 
trks [] . clliZ 

integer 

trks [ ] . qty 
trks [] .used 

used  to  hold  each  record  in  the  trunk  file 

originating  trunk  group  endpoint 
terminating  trunk  group  endpoint 
quantity  of  trunks  in  trunk  group  record 
toggle  to  track  use  of  trunk  group  record 


string  loc  [  ] 

returns  no  formal  values  are  returned 


an  array  used  to  determine  collocation 
for  MCI 


Purpose  To  handle  cases  where  a  trunk  group  exists  with  no  corresponding  path  record. 


Called  By  main ( ) 

Calls  To  outprinto  To  split  trunks  and  print  results  to  an  outfile 

getsize_oneway  ( )  To  add  up  the  trunk  quantity  for  oneway  trunk  group 
getswidx  ( )  To  return  the  index  of  a  switch  CLLI  within  the  switch  list. 


Local 

Variables 

integer  i 


qtyZ 

idxA 

icbcZ 

tot_unused 

Global 

Variables 

integer  numtrunk 
tog_mci 

Algorithmic 

Description 


general  loop  count  variable 

trunk  size  variable  for  Z->A  direction 

A  value  returned  by  getswidx,  the  index  of  the  trunk  group 

originating  endpoint 

A  value  returned  by  getswidx,  the  index  of  the  trunk  group 
terminating  endpoint 

used  to  keep  track  of  the  total  number  of  trunk  records  that  were  not 
used. 


the  number  of  valid  trunk  group  records  read  from  the  trunk  file 
a  toggle  used  to  indicate  MCI  trunks 


For  each  trunk  record,  this  function  checks  to  see  if  the  record  has  been  used.  If  it  has 
not  then  it  checks  for  MCI  trunk  record  ( tog_mci).  If  the  records  are  not  MCI  then  it 
uses  a  matching  process  to  determine  the  collocation,  and  to  create  a  dummy  path  with 
no  spans  and  a  corresponding  trunk  size  record  is  written  to  the  output  file.  If  the  trunk 
record  is  MCI  then  the  function  uses  loc  [  ]  to  determine  collocation. 


Finally,  this  function  prints  to  screen  all  trunk  records  that  did  not  get  used,  as  well  as  a 
total. 
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3.6.6  getsize_oneway  function 


mat_trk  module 


Inputs 


character 

*head 

*tail 

a  character  pointer  used  to  represent  the  originating  end  point  of 
a  trunk  group 

a  character  pointer  used  to  represent  the  terminating  end  point 
of  a  trunk  group 

Outputs 

global 

trk_struct  structure 
with  fields 
character 

integer 

trks  [  ]  used  to  hold  each  record  in  the  trunk  file 

trks  [  ] .  clliA  originating  trunk  group  endpoint 

trks  [  ]  .clliz  terminating  trunk  group  endpoint 

trks  [  ] .  qty  quantity  of  trunks  in  trunk  group  record 

trks  [  ] .  used  toggle  to  track  use  of  trunk  group  record 

returns 

integer 

returns  the  oneway  trunk  size  for  the  switch  endpoints  passed  in 

Purpose 

To  process  the  trunk  size  for  oneway  trunks. 

Called  By 

processpaths ( ) 
processtrunks ( ) 

Calls  To 

none 

Local 

Variables 

integer 

i 

general  loop  count  variable 

Global 

Variables 

integer 

numtrunk 

an  integer  holding  the  number  of  trunks 

Algorithmic 

Description 

This  function  loops  through  the  trunk  group  list,  summing  all  trunk  quantities  with  end 
points  (head,  tail ) .  This  total  is  returned  by  getsize_oneway  ( ) .  The 
trks  [  ] .  used  field  is  set  for  trunks  that  are  used. 
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3.6.7  getsize 


function 


mat_trk  module 


Inputs 

character  *head  a  character  pointer  used  to  represent  the  originating  end  point  of 

a  trunk  group 

*taii  a  character  pointer  used  to  represent  the  terminating  end  point 

of  a  trunk  group 

Outputs 


global 

trk_struct  structure 
with  fields 

trks [ ] 

used  to  hold  each  record  in  the  trunk  file 

character 

trks [] . clliA 
trks [] .clliZ 

originating  trunk  group  endpoint 
terminating  trunk  group  endpoint 

integer 

trks [ ] . qty 
trks [] .used 

quantity  of  trunks  in  trunk  group  record 
toggle  to  track  use  of  trunk  group  record 

returns 

integer 

returns  the  bi-directional  trunk  size  for  the  switch  endpoints 

passed  in 

Purpose  To  compute  and  return  the  total  number  of  trunks  for  a  given  switch  pair. 

Called  By  processpaths  ( ) 

Calls  To  none 

Local 

Variables 

integer  i  general  loop  count  variable 

tot  used  to  hold  the  total  number  of  trunks  to  be  returned 

Global 

Variables  none 
Algorithmic 

Description  This  function  loops  through  the  trunk  group  list,  summing  all  trunk  quantities  with  end 
points  (head,  tail)  or  (tail,  head).  This  total  is  returned  by  getsize().  The 
trks  [  ] .  used  field  is  set  for  trunks  that  are  used.  If  no  trunks  are  found,  (-1 )  is 
returned. 
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3.6.8  getswidx  function  mat_trk  module 


Inputs 

character  *swclli  the  CLLI  code  of  the  switch  for  which  to  search 


Outputs 

global  character  switches  []  The  list  of  IEC  switch  CLLI  codes  to 

search 

returns  integer  the  index  of  swciii  in  vector  switches  [  ] ,  -l  if  not  found 

Purpose  This  short  function  returns  swciii '  s  index  within  switches  [  ]  or  -l  if  it  is  not  a 
member  of  the  list 

Called  By  processtrunks  ( ) 

Calls  To  none 

Local 

Variables 

integer  i  general  loop  count  variable 

Global 

Variables  none 
Algorithmic 

Description  This  function  uses  a  loop  to  sequentially  compare  swciii  to  each  element  in 

switches  [  ] .  It  returns  the  array  index  of  the  first  (and  only)  element  that  matches,  or 
-1  if  no  match  is  found.. 
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3.6.9  outprint 


function 


mat_trk  module 


Inputs 

character  *head  a  character  pointer  used  to  represent  the  originating  end  point  of 

a  trunk  group 

*tail  a  character  pointer  used  to  represent  the  terminating  end  point 

of  a  trunk  group 

qtyA  trunk  size  variable  for  A->Z  direction 

qtyz  trunk  size  variable  for  Z->A  direction 

pathctr  counts  number  of  paths  for  a  given  switch  pair 

Outputs 

global  file  *outfiie  filtered  version  of  the  trunk  file 

returns  no  formal  values  are  returned 

Purpose  To  split  trunks  across  paths  and  print  results  to  an  outfile 

Called  By  processpaths ( ) 
processtrunks ( ) 

Calls  To  none 

Local 

Variables 

integer  i  general  loop  count  variable 

Global 

Variables  none 


Algorithmic 

Description  This  function  calculates  the  ratio  of  trunk  size  (qtyA,  qtyz )  to  the  number  of  paths 
(pathctr)  for  each  (head,  tail )  switch  pair  and  prints  the  results  to  outfile . 


3.7  rem_dups:  Remove  Duplicate  Records  Module 


Purpose  This  module  addresses  an  artifact  of  MCI  data,  namely  duplicate  records  in  the  path  data 
file.  This  module  removes  path  records  that  are  within  two  records  “distance”  of  a 
duplicate  record 

Call  Syntax  rem_dups  -i  cinput  file>  -o  <output  file>  [options] 
mandatory: 

-i  < input  f  ile>  specifies  the  name  of  the  file  containing  the  input 

path  file  records 

-o  <output  file>  specifies  the  name  of  the  file  which  will  hold  the 

filtered  output  path  file 

options: 

-?  user  help-prints  call  syntax  and  exits  without 

running 

example  rem_dups  -i  path_file.MCI  -o  rem_dup.out 

Input 

Files  input 

path  file  Each  record  in  this  file,  specifies  the  physical  transmission  path  between  a 
pair  of  switches.  A  physical  transmission  path  is  defined  by  the  series  of 
spans  (from  none  for  collocated  switches  to  a  limit  of  662)  that  connect  a 
switch  pair.  Spans  are  identified  by  indexes  that  point  to  the  appropriate 
record  number  in  the  span  file. 

format  <switch  CLLI  A>,  <switch  CLLI  Z>,  <span1>,  <span2> . <span  n> 

(ell,  lx,  ell,  lx,  i6,  ... ,  i6) 


example 

ASTI 

NYC1 

3045 

3042 

7579 

237 

NYC1 

ASTI 

3045 

3042 

7579 

237 

NYC1 

AST2 

3045 

3042 

7579 

237 

NYC1 

AST2 

3045 

3042 

7579 

237 

Output 

Files 

output 

path  file  This  file  is  in  the  same  format  as  the  input  path  file,  except  that  duplicate 

records  have  been  removed,  and  switch  endpoints  have  been  arranged  to 
ensure  that  the  first  switch  is  alphabetically  prior  to  the  second  switch. 

format  same  as  input  path  file 

example  ASTI  NYC1  3045  3042  7579  237 

AST2  NYC1  3045  3042  7579  237 

Includes  <stdio.h> 

<stdlib.h> 

<string.h> 

"fileio.c"  see  Appendix  B 

Constants  path_rec  4000  maximum  number  of  characters  in  a  path  file  record 

Global 

Variables  none 
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Local 

Variables 

Variables  local  to  main  ( ) : 

extern 

character 

integer 

*optarg  points  to  a  command  line  argument, 

optind  not  used 

file 

*infp,  *outfp 

pointers  to  the  input  and  output  files 

integer 

tog_infile 

tog_outf ile 

tog_err 

line2_init 

max__path_len 

lenl 

lennext 

i 

toggle  to  indicate  input  Tile  name”  was  read  in  successfully 
toggle  to  indicate  output  “file  name”  was  read  in  successfully 
toggle  to  indicate  an  error  in  the  command  line  arguments 
signals  that  iine2  has  been  initialized  with  a  string  value 
keeps  track  of  the  maximum  path  record  length 
holds  the  length  of  the  path  record  in  linei 
holds  the  length  of  the  path  record  in  nextline 
general  loop  count  variable 

character 

ch 

infile  [] 
outf ile [ ] 
swl  [  ] 
sw2  [  ] 

linei  [PATHREC] 
line2 [PATHREC] 
nextline [PATHREC] 

holds  the  command  line  argument 
holds  the  name  of  the  input  file 
holds  the  name  of  the  output  file 
holds  a  path’s  originating  endpoint 
holds  a  path’s  terminating  endpoint 
holds  a  line  read  in  from  the  input  path  file 

holds  a  line  read  in  from  the  input  path  file 

holds  a  line  read  in  from  the  input  path  file 

Component 

Functions 

none 

Function 

Tree 

none,  main  ( )  only 

Algorithmic 

Description  This  module  addresses  an  artifact  of  MCI  data,  namely  duplicate  records  in  the  path  data 
file.  This  module  removes  path  records  that  are  within  two  records  “distance”  of  a 
duplicate  record 

This  module  consists  solely  of  a  main  ( )  routine  .  The  main  ( )  routine  first  conducts 
initialization  steps:  defines  local  variables;  processes  command  line  arguments;  reads  in 
the  name  of  the  input  file  and  opens  it  in  read  only  mode;  and  reads  in  the  name  of  the 
output  file  and  opens  it  in  write  only  mode. 

The  main  algorithm  of  rem_dup  ( )  tracks  the  last  two  unique  path  file  records,  with 
which  subsequent  records  are  compared  to  determine  duplication.  The  main  algorithm 
is  initialized  by  loading  the  first  path  record  into  linei  and  printing  this  line  to  the 
output  file.  Subsequent  records  are  read  into  nextline  and  compared  to  linei.  As 
soon  as  a  second  unique  path  record  is  found,  it  is  copied  from  nextline  to  line2 
and  written  to  the  output  file.. 

Once  linei  and  Iine2  are  initialized  ,  they  are  used  as  a  queue  data  structure  to  hold 
the  last  two  unique  path  records.  When  nextline  is  found  to  be  different  from  linei 
and  Iine2: 
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•  nextline  is  printed  to  the  output  file 

•  linel  shifted  out  of  queue 

•  line2  is  shifted  to  linel 

•  nextline  is  Shifted  to  line2 

Pathfile  records  are  always  printed  out  such  that  the  endpoint  CLLI  codes  are  in 
alphabetical  order.  The  algorithm  above  is  continued  until  the  end  of  the  file  is  reached. 
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3.8  sort_paths:  Sorting  of  path  file  module 


Purpose  This  module  is  used  to  sort  the  records  in  the  MCI  path  file 

Call  Syntax  sort_paths  -i  cinput  f ile>  -o  <output  file>  [options] 
mandatory: 

-i  < input  file>  specifies  the  name  of  the  file  containing  the  input 

path  file  records 

-o  <output  f  iie>  specifies  the  name  of  the  file  which  will  hold  the 

filtered  output  path  file 

options: 

-?  user  help-prints  call  syntax  and  exits  without  running 
example  sort_paths  -i  infile  -o  outfile 

Input 

Files  input 

path  file  Each  record  in  this  file  specifies  the  physical  transmission  path  between  a  pair 
of  switches.  A  physical  transmission  path  is  defined  by  the  series  of  spans 
(from  none  for  collocated  switches  to  a  limit  of  662)  that  connect  a  switch  pair. 
Spans  are  identified  by  indexes  that  point  to  the  appropriate  record  number 
in  the  span  file. 

format  <switch  CLLI  A>,  <switch  CLLI  Z>,  <span1>,  <span2>, ... ,  <span  n> 
(cl  1 ,  lx,  c11,1x,i6,  i6,...  ,i6) 

example  ASTI  NYC2  3045  3042  7579  237 

ASTI  NYC1  3045  3042  7579  237 

Output 

Files  output 

path  file  This  file  is  in  the  same  format  as  the  input  path  file,  except  that  records  have 
been  sorted  in  alphabetical  ascending  order. 

format  same  as  input  path  file 

example  asti  nyci  3045  3042  7579  237 

ASTI  NYC2  3045  3042  7579  237 

Includes  <stdio.h> 

<stdlib.h> 

< string. h> 

" f ileio .  c"  see  Appendix  B. 

Constants  path_rec  3700  maximum  number  of  characters  in  a  path  file  record 

num_path  12700  maximum  number  of  path  records  capable  of  being  read 

Global 

Variables 

integer  num_rec  counts  the  number  of  path  records  read  from  the  input  file 

character  paths  [  ]  [  ]  an  array  used  to  store  every  record  read  from  the  input  file  for  use  during  the 

sorting  routine . 

file  *infp,  *outfp  pointers  to  the  input  and  output  files 
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Local 

Variables 

extern 


integer 


character 


Component 

Functions 


Function 

Tree 


Algorithmic 

Description 


Variables  local  to  main  ( ) : 


character 

integer 


*optarg 

optind 


points  to  the  current  command  line  argument 
being  parsed 
not  used 


tog_inf ile 
tog_outf ile 
tog_err 
i 


toggle  to  indicate  input  file  was  read  in  successfully 
toggle  to  indicate  output  file  was  read  in  successfully 
toggle  to  indicate  an  error  in  the  command  line  arguments 
general  loop  count  variable 


ch 

infile [ ] 
outf ile [ ] 


used  to  parse  command  line  options 
holds  the  name  of  the  input  file 
holds  the  name  of  the  output  file 


char_comp  ( )  string  comparison  routine  for  qsort  ( ) . 

qsort  ( )  standard  ‘C’  sorting  routine 


main  ( )  — qsort  ( )  — char_comp  ( ) 


This  module  is  used  to  sort  the  records  in  the  path  file  for  MCI  data.  Essentially  it  reads 
the  input  file  into  an  array,  passes  the  array  to  the  standard  ‘C’  sort  routine  and  prints  the 
result  to  the  output. 

The  main  ( )  routine  first  conducts  initialization  steps:  defines  local  variables; 
processes  command  line  arguments  ;  reads  in  the  name  of  the  input  file  and  opens  it  in 
read  only  mode;  and  reads  in  the  name  of  the  output  file  and  opens  it  in  write  only 
mode. 

Then,  the  main  algorithm  of  this  function  loads  each  record  in  the  input  file  into  the  array 
paths  [  ]  [  ]  and  passes  the  array  to  the  standard  ‘C’  qsort  ( )  routine.  Qsort  ( )  uses 
char_comp  ( )  to  sort  records  in  ascending  order  and  modifies  the  records  of 
paths  [  ]  [  ]  until  they  are  completely  sorted.  Finally  this  module  prints  the  sorted 
records  from  paths  [  ]  [  ]  to  the  output  file 


3-44 


3.9  clli3_4:  Location  to  Switch  Code  Conversion  module 


Purpose 


Call  Syntax 


example 

Input 

Files 


Output 

Files 


This  module  addresses  a  shortfall  in  MCI  data  only.  It  converts  the  endpoints  in  path  file 
records  from  3  character  location  codes  to  4  character  switch  codes.  Where  more  than 
one  switch  resides  at  a  location,  all  possible  combinations  are  produced.  This  step  is 
necessary  in  order  to  correlate  physical  paths  to  trunk  groups  (which  have  switch  code 
endpoints)  in  the  mat_trk  module. 

clli3_4  <filename> 

where  <f  iiename>  specifies  the  name  of  the  input  file  containing  a  list  of  all  other  input 
and  output  files 

clli3_4  MCIf iles . fy94 


list  file  This  file  simply  contains  the  names  of  the  two  input  files  and  one 
output  file.  File  names  are  limited  by  cili3_4  to  a  length  of  50 
characters. 


format  linel :  <input  path  file  name> 

Iine2:  <switch  location  file> 

Iine3:  coutput  path  file  name> 

input 

path  file  Each  record  in  this  file,  specifies  the  physical  transmission  path 

between  a  pair  of  switches.  A  physical  transmission  path  is  defined 
by  the  series  of  spans  (from  none  for  collocated  switches  to  a  limit  of 
662)  that  connect  a  switch  pair.  Spans  are  identified  by  indexes  that 
point  to  the  appropriate  record  number  in  the  span  file. 

format  <switch  CLLI  A>,  <switch  CLLI  Z>,  <span1>,  <span2>, ... ,  <span  n> 
(ell,  1x,c11,  lx,  i6,  i6 . i6) 

example  AST  NYC  3045  3042  7579  237 

switch 

location  file  This  file  contains  each  MCI  4  character  switch  code,  followed  by  its  3 
character  location  code.  The  location  code  identifies  the  building  in 
which  the  switch  is  housed. 


format  <switch  code>,  <location  code> 
(c4,  lx,  c3) 

example  asti  ast 

AST 2  AST 
NYC1  NYC 


output 

path  file  This  file  is  in  the  same  format  as  the  input  path  file,  except  that  each 
path  endpoint  has  been  mapped  from  a  location  code  to  all  possible 
combinations  of  switch  codes. 

format  same  as  input  path  file 
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Includes 

Constants 

Global 

Variables 

file 

integer 

character 

structure 


Component 

Functions 


Function 

Tree 


Algorithmic 

Description 


example  ASTI  NYC1  3045  3042  7579  237 

AST2  NYC1  3045  3042  7579  237 

<stdio.h> 

<string.h> 

"fileio.c"  See  Appendix  B 

maxline  4000  maximum  number  of  characters  in  a  path  file  record 


*pathfile,  *locfile,  *outfile,  *filelist 

pointers  to  the  input  and  output  files 

num_nodes  counts  the  number  of  switches  read  from  the  switch  location  file 


line [MAXLINE] 

holds  a  line  read  from  the  input  path  file 


mapp_struct 

with  field 
character 


mapp [ ] 


used  to  hold  each  record  in  the  switch 
location  file 


mapp  [  ] .  three  holds  MCI  three  character  location  code 
read  in  from  the  switch  location  file 
mapp  [  ] .  four  holds  MCI  four  character  switch  code 
read  in  from  the  switch  location  file 


openfiles ( ) 
readmappings ( ) 

createpathfile ( ) 

closefiles ( ) 


opens  input  and  output  files 

reads  in  the  list  of  switch  and  location  codes  from  the 

switch  location  file 

maps  the  path  endpoints  from  3  character  location  codes  to  4 
character  switch  codes 
closes  input  and  output  files 


main ( )  H 


j— openfiles  ( ) 

- readmappings ( ) 

-  createpathfile ( ) 

-  closefiles ( ) 


This  module  addresses  a  shortfall  in  MCI  data  only.  It  converts  the  endpoints  in  path  file 
records  from  3  character  location  codes  to  4  character  switch  codes.  Where  more  than 
one  switch  resides  at  a  location,  all  possible  combinations  are  produced.  For  example,  a 
path  between  two  locations  which  house  2  and  3  switches  respectively  would  be 
mapped  to  the  6  possible  switch-to-switch  paths.  This  module  is  required  for  the 
subsequent  running  of  the  mat_trk  module,  which  correlates  the  logical  trunk  group 
file  with  the  physical  path  file  based  on  the  switch  endpoints  of  each  record. 

The  main  ( )  routine  passes  the  <f  iiename>  argument  (the  name  of  the  file  list  file)  to 
openfiles  ( ) .  Openfiles  ( )  opens  all  input  and  output  files  whose  names  are 
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contained  in  the  file  list.  Then  readmappings  ( )  is  called  to  read  the  contents  of  the 
switch  location  file  into  the  mapp  [  ]  structure.  Main()  calls  createpathfilef )  to 
apply  the  location-to-switch  endpoint  mapping  to  each  record  of  the  input  path  file, 
thereby  creating  the  output  path  file,  ciosefiles  ( )  is  called  to  close  all  files  before 
the  module  terminates. 
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3.9.1  openfiles 


function 


clli3_4  module 


Inputs 

character  files  string  containing  the  name  of  the  file  that  lists  the  three  input/output  files 

Outputs 

global  file  *f ilelist  points  to  the  file  whose  name  is  contained  in  the  files 

string 

*pathf  ile  points  to  the  input  physical  transmission  path  file,  using 

location  endpoints 

*locf  ile  points  to  a  file  that  lists  the  MCI  4  character  switch  codes 

and  corresponding3  character  location  codes 
*outf  ile  filtered  version  of  path  file  using  switch  endpoints 
instead  of  location  endpoints. 

returns  no  formal  values  are  returned 
Purpose  To  open  path  and  location  input  files  and  the  output  path  file. 

Called  By  main ( ) 

Calls  To  none 

Local 

Variables 

character  tempf  ile  [50]  this  variable  is  used  temporarily  to  hold  the  name  of  the  next  file  to  be 

opened  and  read  in  from  the  list  of  files  in  f  ilelist 

Global 

Variables  none 
Algorithmic 

Description  This  function  opens  the  file  whose  name  is  stored  in  the  string  files,  setting  a  file 
pointer,  f  ilelist.  Filelist  contains  a  list  of  all  the  input/output  files  to  be 
opened  in  the  following  order:  pathfile,  locfile  and  outfile.  This  function 
then  proceeds  to  open  each  of  these  files,  in  the  order  they  are  read  in  from  filelist, 
assigning  them  to  the  matching  file  pointers. 

Errors  encountered  during  any  file  opening  operation  result  in  an  error  message  being 
printed  to  the  screen,  and  termination  of  the  module. 
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3.9.2  readmappings  function 


clli3_4  module 


Inputs 

Outputs 

global 


returns 

Purpose 

Called  By 

Calls  To 

Local 

Variables 

integer 

Global 

Variables 

integer 

file 

Algorithmic 

Description 


none;  operates  on  global  variables 


mapp_struct  structure  mapp  [  ] 

with  fields 

Character  mapp  [  ] .  three 

mapp [ ] . four 


holds  the  records  from  the  switch 
location  file 

holds  MCI  three-character  location  code 
holds  MCI  four-character  switch  code 


no  formal  values  are  returned 

To  read  the  list  of  switch  codes  and  corresponding  location  codes  from  the  switch 
location  file,  into  the  mapp  [  ]  structure. 

main ( ) 

none 


i 


general  loop  count  variable 


num_nodes  the  total  number  of  switch  records  read 

*iocf  ile  points  to  the  switch  location  file 


This  function  reads  the  switch  location  file  line  by  line,  loading  each  location  code  into 
the  mapp  [  ] .  three  field  and  each  switch  code  into  the  mapp  [  ] .  four  field,  and 
setting  num_nodes  to  the  total  number  of  records  in  the  switch  location  file. 
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3.9.3  createpathfile  function 


clli3_4  module 


Inputs  none;  operates  on  global  variables 

Outputs 


returns 

no  formal  values  are  returned;  outputs  are  written  directly  to  the  output  file 

Purpose 

This  function  maps  the  path  endpoints  from  three  character  location  codes  to  all 
possible  combinations  of  four  character  switch  codes. 

Called  By 

main ( ) 

Calls  To 

none 

Local 

Variables 

integer 

i 

len 

foundl=0 

found2=0 

posl 
pos2 
f irst2 

general  loop  count  variable 
used  to  hold  the  string  length  of  a  pathf  ile  line 
a  toggle  used  to  indicate  whether  swl  was  found  in  the 
mapp_struct  structure 

a  toggle  used  to  indicate  whether  sw2  was  found  in  the 
mapp_struct  structure 

the  index  of  swl  within  the  mapp_struct  structure 
the  index  of  sw2  within  the  mapp_struct  structure 
temporarily  holds  the  value  of  pos2 

character 

swl 

sw2 

the  originating  endpoint  of  the  current  path 
the  terminating  endpoint  of  the  current  path 

Global 

Variables 

integer 

num__nodes 

the  number  of  records  in  the  pathf  ile 

character 

line[] 

a  line  of  input  from  the  pathf  ile 

structure 

mapp_struct 

with  fields 
character 

mapp  [  ]  used  to  hold  each  record  from  the  switch 

location  file 

mapp  [  ] .  three  three  character  location  code 
mapp  [  ] .  four  four  character  switch  code 

Algorithmic 

Description  This  function  processes  the  path  file,  record  by  record,  loading  the  three  character 

location  for  the  originating  and  terminating  endpoints  into  the  string  variables  swl  and 
sw2 .  Next  this  function  searches  the  mapp  [  ]  structure  for  each  of  the  four  character 
switch  CLLI  codes,  at  locations  swl  and  sw2 .  A  path  record  is  printed  to  the  output  file 
for  every  combination  of  switch  CLLI  code  endpoints  at  locations  swl  and  sw2 


3-50 


The  following  example  illustrates  the  dataflow  performed  by  createpathfile() 
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3.9.4  closefiles 


function 


clli3_4  module 


Inputs 

none;  operates  on  global  variables 

Outputs 

global 

file  *pathfile  points  to  a  file  that  contains  information  on  the  physical 

transmission  paths  between  pairs  of  switches 
*locf  ile  points  to  a  file  that  contains  the  list  of  MCI  4  character 

switch  codes  and  3  character  location  codes 
*outf  ile  filtered  version  of  path  file 

returns 

no  formal  values  are  returned 

Purpose 

To  close  path  and  location  input  files  and  the  output  file. 

Called  By 

main ( ) 

Calls  To 

none 

Local 

Variables 

none 

Global 

Variables 

none 

Algorithmic 

Description 

This  function  closes  the  files  whose  names  are  pointed  to  by  the  following  pointers: 
pathfile,  locfile  and  outf ile,  in  the  order  given. 
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3.10  mkpath:  Make  Path  module 


Purpose  This  module  consolidates  the  trunk  and  path  files  output  from  mat_trk.  Switch  CLLI 
codes  are  replaced  with  index  numbers  that  reference  the  switch  list. 

Call  Syntax  mkpath  <filename> 

where  <f  iiename>  specifies  the  name  of  the  input  file  containing  a  list  of  all  other  input 
and  output  files 

example  mkpath  MCIfiles.fy94 

Input 

Fi|es  list  file  This  file  simply  contains  the  names  of  the  three  input  files  and  one 

output  file  to  be  used  by  mkpath.  File  names  are  limited  by  mkpath 
to  a  length  of  50  characters. 

format  linel:  <path  file  name> 

Iine2:  <switch  file  name> 

Iine3:  ctrunk  file  name> 

Iine4:  <output  file  name> 

switch  file  This  file  contains  the  list  of  codes  for  IEC  backbone  switches. 

format  <IEC  switch  CLLI  code> 

(ell) 

trunk  file  The  trunk  file  specifies  the  IEC  switch  CLLI  codes  of  the  trunk 
endpoints,  the  number  of  trunks  in  the  A  to  Z  direction  (or  all  bi¬ 
directional  trunks),  and  the  number  of  trunks  in  the  Z  to  A  direction 
(only  used  for  one-way  trunk  groups).  Each  record  is  in  1  -to-1 
correspondence  with  the  path  file.  That  is,  the  number  of  trunks  in 
the  nth  trunk  file  record  traverse  the  transmission  path  specified  by 
the  nth  path  file  record. 

format  <switch  CLLI  A>,  <switch  CLLI  Z>,  <A->Z  trunk  quantity:*,  <Z->A 
trunk  quantity> 

(cl  1 ,  lx,  ell,  lx,  i4,  lx,  i4) 

pqth  file  Each  record  in  this  file,  created  by  the  mat_trk  module,  specifies 

the  physical  transmission  path  between  a  pair  of  switches.  A  physical 
transmission  path  is  defined  by  the  series  of  spans  (from  none  for 
collocated  switches  to  a  limit  of  662)  that  connect  a  switch  pair. 

Spans  are  identified  by  indexes  that  point  to  the  appropriate  record 
number  in  the  span  file. 

format  <switch  CLLI  A>,  <switch  CLLI  Z>,  <span1>,  <span2> . <span  n> 

(cl  1 ,  lx,  cl  1 ,  lx,  i6,  i6 . i6) 

Output 

Files  output  trunk/ 

path  file  The  output  trunk/path  file  combines  the  logical  trunk  and  physical 

path  records  into  a  single  record  format  that  specifies  trunk  quantities 


3-53 


Includes 


Constants 

Global 

Variables 

file 

integer 

character 

structure 


Component 

Functions 


Function 

Tree 


Algorithmic 

Description 


per  physical  path.  The  format  specifies  the  index  numbers  of  the  IEC 
switch  endpoints,  the  number  of  trunks  in  the  A  to  Z  direction  (or  all 
bi-directional  trunks),  the  number  of  trunks  in  the  Z  to  A  direction 
(only  used  for  one-way  trunk  groups),  and  a  series  of  span  index 
numbers  that  define  the  physical  transmission  path. 

format  <switch  index  A>,  <switch  index  Z>,  <A->Z  trunk  quantity>,  <Z->A 
trunk  quantity;*,  <span1>,  <span2>, ... ,  <span  n> 

(i6,  i6,  i6,  i6,  [spans:]  i6,  i6 . i6) 

<stdio.h> 

<string.h> 

"fileio.c"  See  Appendix  B 


maxpath  4000  maximum  number  of  characters  in  a  path  file  record 
clli_lng  12  length  of  a  switch  CLLI  code,  including  terminating  null  character 
maxsw  200  maximum  number  of  records  in  the  switch  file 


*pathfile,  *switchfile,  *trunkfile,  *filelist,  *outfile 
pointers  to  the  input  and  output  files 

num_nodes  the  number  of  records  read  in  from  the  switch  file 

line  [maxpath]  used  to  hold  a  line  of  input  from  the  path  file 

swiine  [maxsw]  used  to  hold  a  line  of  input  from  the  switch  file 

sw [MAXSW]  of  type  switch_struct 
with  fields: 

character  sw  [  ] .  clli  used  to  hold  the  list  of  switch  CLLI  codes 


openfiles ( ) 
readswitches ( ) 
createpathf ile ( ) 
closefiles ( ) 


opens  input  and  output  files 

reads  in  the  list  of  switches  from  the  switch  file 

combines  path  and  trunk  records  into  a  single  output  record 

closes  input  and  output  files 


main ( )  H 


P openfiles  { ) 

|—  readswitches  ( ) 
createpathf ile ( ) 
closefiles ( ) 


This  module  performs  the  simple  task  of  consolidating  the  trunk  and  path  files  output 
from  mat_trk  and  replacing  switch  CLLI  codes  with  index  numbers  that  reference  the 
switch  list.  Because  the  trunk  and  path  file  records  are  already  in  one-to-one 
correspondence,  mkpath  essentially  concatenates  the  two  records  into  a  single  output 
record  format. 

The  program  begins  by  calling  openfiles  ( )  to  open  the  input  and  output  files.  Next, 
readswitches  ( )  is  called  to  load  the  switch  list  into  the  sw [  ]  structure.  Then, 
createpathf  ile  ( )  is  called  to  perform  the  main  algorithm.  This  routine  reads  in  a 
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path  record  and  a  trunk  record.  It  parses  the  switch  endpoint  CLLI  codes  from  the  path 
record,  and  searches  through  the  switch  structure  to  determine  the  corresponding 
switch  index  numbers.  The  output  record  is  written  using  these  index  numbers,  along 
with  the  trunk  quantity  and  transmission  path  information.  Note  that  no  processing  or 
filtering  is  performed  on  either  the  trunk  or  path  records. 

The  following  example  shows  the  data  flow  through  mkpath  that  maps  corresponding 
path  and  trunk  records  into  a  single  output  record: 
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3.10.1  openfiles 


function 


mkpath  module 


Inputs 

character 

Outputs 

global 


returns 

Purpose 

Called  By 

Calls  To 

Local 

Variables 

character 

Global 

Variables 

Algorithmic 

Description 


files  string  containing  the  name  of  the  file  that  lists  the  five  input/output  files 


file 


*f ilelist 
*pathf ile 
*switchfile 
*trunkfile 
*outfile 


points  to  the  file  whose  name  is  contained  in  the  files 
string 

points  to  a  file  that  contains  information  on  the  physical 
paths  and  switches 

points  to  a  file  that  contains  information  on  the  backbone 
network  switches 

points  to  a  file  that  contains  information  on  the  logical 
trunks 

filtered  version  of  path  file 


no  formal  values  are  returned 


To  open  path,  trunk  and  switch  input  files  and  the  path  output  file. 


main ( ) 


none 


tempf  ile  [ 50  ]  this  variable  is  used  temporarily  to  hold  the  name  of  the  next  file  to  be 
opened  and  read  in  from  the  list  of  files  in  f  ilelist 


none 


This  function  opens  the  file  whose  name  is  stored  in  the  string  files,  setting  a 
filepointer  to  f  ilelist .  Filelist  contains  a  list  of  all  the  input  files  to  be  opened 
in  the  following  order:  pathfile,  switchfile,  trunkfile,  and  outfile. 
This  function  then  proceeds  to  open  each  of  these  files,  in  the  order  they  are  read  in 
from  filelist,  assigning  them  to  the  matching  filepointers. 

Errors  encountered  during  any  file  opening  operation  result  in  an  error  message  being 
printed  to  the  screen,  and  termination  of  the  module. 
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3.10.2  readswitches 


function 


mkpath  module 


Inputs 

Outputs 

global 


returns 

Purpose 

Called  By 

Calls  To 

Local 

Variables 

integer 

Global 

Variables 

character 

Algorithmic 

Description 


none;  operates  on  global  variables 


switch_struct  structure  sw  [  ] 
with  field.-s 

character  sw[].clli 

integer  num_nodes 

file  *switchfile 

no  formal  values  are  returned 
To  read  the  list  of  switch  CLLI  codes  from 


used  to  hold  each  record  in  the  switch 
file 

holds  switch  endpoints  read  in  from  the 
switchfile 

used  to  count  the  number  of  records  in 

the  switchfile 

points  to  the  switch  file 


the  switch  file  into  the  sw  [  ]  structure. 


main ( ) 


none 


i  general  loop  count  variable 


swline  [  ]  used  to  hold  a  line  of  input  from  the  switch  file 


This  function  reads  the  switch  file  line  by  line,  loading  each  CLLI  code  into  the  structure 
sw  [  ]  and  setting  num_nodes  to  the  total  number  of  switches  in  the  switch  file. 
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3.10.3  createpathfile 


function 


mkpath  module 


Inputs  none;  operates  on  global  variables 

Outputs 

returns  no  formal  values  are  returned;  outputs  are  written  directly  to  the  output  file 

Purpose  This  function  consolidates  the  trunk  and  path  files  output  from  mat_trk.  Switch  CLLI 
codes  are  replaced  with  index  numbers  that  reference  the  switch  list. 

Called  By  main  ( ) 

Calls  To  none 

Local 

Variables 

integer  i,  j  general  loop  count  variables 

len  used  to  hold  the  string  length  of  a  pa thfile  line 

trunksizeA  the  number  of  trunks  in  the  A  ->Z  direction 

trunksizez  the  number  of  trunks  in  the  Z  ->A  direction 

character  tempi  [  ]  used  to  hold  the  originating  endpoint  of  a  path 

temp2  [  ]  used  to  hold  the  terminating  endpoint  of  a  path 

trkline  [  ]  temporarily  holds  a  record  from  the  trunkf  ile 


Global 

Variables 

integer  num_nodes  used  to  hold  the  number  of  records  in  the  switchf  ile 

character  iine[]  used  to  hold  a  line  of  input  from  the  pathf  ile 

Algorithmic 

Description  This  function  processes  the  trunk  and  path  files,  record-by-record,  combining  the 

information  into  a  single  output  file  record.  For  each  line  (record)  in  the  trunk  file,  this 
function  parses  the  number  of  trunks  in  the  A->Z  and  the  Z->A  directions,  and  stores 
these  fields  in  trunksizeA  and  trunksizez,  respectively.  For  each  line  (record)  in 
the  path  file,  the  function  parses  the  originating  and  terminating  path  endpoints,  and 
stores  these  fields  in  tempi  and  temp2,  respectively. 

This  function  then  derives  indices  to  replace  switch  CLLI  codes  by  locating  the  position 
of  tempi /temp2  within  sw  [  ] .  A  combined  trunk/path  record  is  written  to  the  output  file 
as:  switch  1  index,  switch  2  index,  trunksize  of  A,  trunksize  of  Z,  spans  (repeated  from 
input  path  record). 
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3.10.4  closefiles 


function 


mkpath  module 


Inputs  none;  operates  on  global  variables 

Outputs 

global  file  *trunkfiie  points  to  a  file  that  contains  information  on  the  logical 

trunks 

*switchf  ile  points  to  a  file  that  contains  information  on  the  backbone 
network  switches 

*pathf  ile  points  to  a  file  that  contains  information  on  the  physical 

paths  and  switches 

*outfiie  combined  and  indexed  trunk  and  path  file 
returns  no  formal  values  are  returned 
Purpose  To  close  trunk,  switch  and  path  input  files  and  the  output  file. 

Called  By  main  ( ) 

Calls  To  none 

Local 

Variables  none 
Global 

Variables  none 

Algorithmic 

Description 

This  function  closes  the  files  whose  names  are  pointed  to  by  the  following  pointers: 
trunkfile,  switchfile,  pathfile  and  outf  ile,  in  the  order  given. 
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3.11  damage:  Monte  Carlo  Damage  module 


Purpose  For  every  network  asset,  this  program  generates  a  number  of  Monte  Carlo  damage 
values.  A  damage  value  is  either  a  0  to  indicate  equipment  failure,  or  a  1  to  indicate 
survival.  Two  general  categories  of  assets  are  damaged:  nodes  and  spans.  Damage  is 
based  on  equipment  type.  Each  type  has  a  cumulative  distribution  function  (CDF) 
which  defines  the  equipment’s  probability  of  failure.  Specifically,  this  module  is 
designed  to  apply  electromagnetic  pulse  (EMP)  damage  to  network  facilities. 


Call  Syntax 


damage  -i  <filename>  [options] 

mandatory: 

-i  <f  iiename>  specifies  the  name  (<f  ilename>)  of  the  input  keyfile  which 
contains  a  list  of  the  run  parameters  and  input/output  asset 
filenames 


options: 

-a 

-h 

-P 


-s  <integer> 
_? 


adds  a  live  damage  vector  to  the  output  file 

uses  10dB  shielding  CDF’s  for  AT&T  Series  G  fiber  damage 

rather  than  the  default  6dB  shielding  (EMP  specific) 

uses  AT&T  Series  G  fiber  CDF’s  without  power  supply  failure 

for  damage  rather  than  the  default  6dB  shielding  (EMP 

specific) 

sets  the  random  number  stream  (1-15) 

user  help-prints  call  syntax  and  exits  without  running 


example  damage  -i  ATTassetts .  key  -s  6  -a  -h  (spaces  optional) 


Input 

Files 


keyfile  This  file  contains  the  input  parameters  and  asset  filenames  to  be 
used  by  damage.  The  parameters  specify  the  type  of  damage  to 
perform  (EMP  vs.  fallout  radiation),  the  number  of  damage  vectors  to 
generate  in  each  of  three  intensity  ranges  (low,  medium,  and  high), 
whether  to  include  the  effects  of  switch  upset,  and  the  name  of  the 
CDF  file.  CDF  and  asset  file  names  are  limited  by  damage  to  a  length 
of  80  characters. 


format  linel: 

Iine2: 

Iine3: 

Iine4: 

Iine5+: 


<damage  type> 

either  emp  or  fr  (fallout  radiation) 

cnumber  of  low  damage  vectors>,<medium>,<high> 

(i,  lx,  i,  lx,  i) 

<switch  upset  toggle> 
either  upset_on  or  upset_off 
<CDF  file  name> 

<node/span  indicator  (N/s)>,<asset  file>,<damage  file> 
(cl  ,1x,c,1x,c) 

example  node  file:  n  switchlist  switchiist.dmg 
example  span  file:  S  spanlist  spanlist.dmg 


node  file  This  file  contains  a  list  of  switches.  Each  line  contains  an  1 1  -character 
CLLI  code  followed  by  a  3-character  equipment  code  (see  algorithm 
description  for  details).  Any  information  following  the  equipment 
type  is  ignored. 

format:  <switch  CLLI  code>, equipment  code> 

(cl  1,  lx,  c3) 
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SPan  file  This  file  contains  the  list  of  spans.  Each  line  contains  2  1 1  -character 
CLLI  codes  (the  two  span  endpoints),  a  2-character  equipment  code 
(see  algorithm  description  for  details),  and  V-H  coordinates  for  each 
endpoint.  Any  information  following  the  coordinates  is  ignored. 

format:  <CLLI  A>,<CLLI  Z>, equipment  code>,<V-coord  A>,<H-coord  A>, 

<V-coord  B>,<H-coord  B> 

(cl  1 ,  lx,  cl  1 ,  lx,  c2,  lx,  i5,  lx,  i5,  lx,  i5,  lx,  i5) 

CDF  file  This  file  contains  the  data  points  for  the  CDF  curves  for  all  of  the  node 
and  span  equipment  to  be  damaged.  Each  CDF  consists  of  100  data 
points  listed  5  per  line  (i.e.,  20  lines  per  curve).  The  file  contains  the 
y-values  of  the  curve  for  0<x<1  in  0.1  increments.  There  are  no 
divisions  or  indicators  between  CDF’s.  The  identity  of  each  CDF  is 
given  by  a  key  in  the  damage  code  (described  in  the  Constants 
section  below). 

format  <data  point>,<data  point>,<data  point>,<data  point>,<data  point> 

(el 3.7,  lx,  el 3.7,  lx,  el 3.7,  lx,  el 3.7,  lx,  el 3.7) 

Output 

Files  output  node  file  Each  line  of  this  file  contains  a  CLLI  code  followed  by  a  number  of 

damage  values  (0  indicates  equipment,  1  indicates  survival).  Each 
line  contains  the  same  number  of  damage  values.  This  number  of 
specified  in  the  keyfile. 

format  <switch  CLLI  A>,  <damage  values  1 ,2,3, ...,n> 

(ell,  lx,  il,  il,  il . il) 

output  span  file  Each  line  of  this  file  contains  the  two  endpoint  CLLI  codes  followed 
by  a  number  of  damage  values  (0  indicates  equipment,  1  indicates 
survival).  Each  line  contains  the  same  number  of  damage  values. 

This  number  of  specified  in  the  keyfile. 

format  <CLLI  A>,  <CLLI  B>,  <damage  values  1 ,2,3,...,n> 

(ell,  lx,  ell,  lx,  il,  il,  il . il) 


Includes  <stdio.h> 

<math . h> 

"fileio.c"  See  Appendix  B 

"/user/gretchen/waglib/waglib.h"  Random  number  generator 


Constants 


MAX_CDF 

75 

maximum  number  of  CDF  curves  in  a  CDF  file 

MAX_SUP 

25 

maximum  number  of  supplemental  CDF  curves  in  a  CDF  file 

FALSE 

0 

logical  false 

NONE  ( 

-1) 

no  curve  selected 

ANASWT 

0 

CDF  index:  generic  analog  switch 

DIGSWT 

3 

CDF  index:  generic  digital  switch 

L4COAX 

6 

CDF  index:  L4  coaxial  transmission  system 

TIOFFC 

9 

CDF  index:  T1  carrier  with  office  repeater 

T1LINE 

12 

CDF  index:  T1  carrier  with  line  repeater 

FT 3 SWT 

15 

CDF  index:  AT&T  fiber  carrier  with  FT3C  terminal 

FT3RPT 

18 

CDF  index:  AT&T  fiber  carrier  with  FT3C  repeater 

MWTD2 

21 

CDF  index:  TD-2  analog  microwave 

ATT4ES 

24 

CDF  index:  AT&T  4ESS  switch  (damage  curve) 

FORI 40 

27 

CDF  index:  Alcatel  fiber  carrier  with  R-R140  repeater 

DMS100 

30 

CDF  index:  NT  DMS-100  switch  (damage  curve) 
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DMSUPS 

33 

CDF  index: 

ATT4EU 

36 

CDF  index: 

ATT5ES 

39 

CDF  index: 

ATT5EU 

42 

CDF  index: 

FTGDMG 

45 

CDF  index: 

FTGUPS 

48 

CDF  index: 

FTG6D 

45 

CDF  index: 

FTG6U 

54 

CDF  index: 

FD565 

57 

CDF  index: 

FTG10D 

60 

CDF  index: 

FTG10U 

63 

CDF  index: 

FTGPSD 

45 

CDF  index: 

FTGPSU 

45 

CDF  index: 

SUPFTG6D 

0 

CDF  index: 

SUPFTG6U 

3 

CDF  index: 

SUPFTG10D 

6 

CDF  index: 

SUPFTG10U 

9 

CDF  index: 

SUPFD565 

12 

CDF  index: 

SUPFTGPSD 

15 

CDF  index: 

SUPFTGPSD 

15 

CDF  index: 

RAD4ES 

0 

CDF  index: 

RAD5ES 

0 

CDF  index: 

RADFOR 

3 

CDF  index: 

NT  DMS-100  switch  (upset  curve) 

AT&T  4ESS  switch  (upset  curve) 

AT&T  5ESS  switch  (damage  curve) 

AT&T  5ESS  switch  (upset  curve) 

AT&T  Series  G  fiber  (damage  curve) 

AT&T  Series  G  fiber  (upset  curve) 

Series  G  with  6dB  shielding  (damage) 

Series  G  with  6dB  shielding  (upset) 

NTI FD-565  fiber  terminal 

Series  G  with  10dB  shielding  (damage) 

Series  G  with  10dB  shielding  (upset) 

Series  G  ignoring  damage  to  power  supply  (damage) 
Series  G  ignoring  damage  to  power  supply  (upset) 

Series  G  (6dB)  supplemental  data  points 
Series  G  (6dB)  supplemental  data  points 
Series  G  (10dB)  supplemental  data  points 
Series  G  (10dB)  supplemental  data  points 
FD-565  supplemental  data  points 
Series  G  (power  supply)  supplemental  data  points 
Series  G  (power  supply)  supplemental  data  points 

AT&T  4ESS  fallout  radiation  curves 
AT&T  5ESS  fallout  radiation  curves 
fiber  optic  fallout  radiation  curves 


Local 

Variables  Variables  local  to  main  ( ) : 


integer  err 
itog 
stog 
htog 
Ptog 
VA 
HA 
VZ 
HZ 
i 
j 

count 

optind 

argc 


an  error  flag  indicating  a  problem  with  the  command  line  arguments 

a  flag  indicating  that  the  -i  command  line  option  is  set 

a  flag  indicating  that  the  -s  command  line  option  is  set 

a  flag  indicating  that  the  -h  command  line  option  is  set 

a  flag  indicating  that  the  -p  command  line  option  is  set 

vertical  coordinate  of  node  A 

horizontal  coordinate  of  node  A 

vertical  coordinate  of  node  Z 

horizontal  coordinate  of  node  Z 

an  index  variable 

an  index  variable 

an  output  counter 

the  number  of  a  single  command  line  arguments 
the  number  of  command  line  arguments 


character  input_f  ile  [  50  ]  used  to  read  a  file  name  from  a  prompt 
ch  a  single  character 

1  ine  [100]  holds  a  single  input  line  from  a  file 

temp  [  6  ]  used  to  parse  a  line 

clliA[l2  ]  the  CLLI  code  for  node  A 

ciliz  [12  ]  the  CLLI  code  for  node  Z 

equip  [  4  ]  an  equipment  code 

*optarg  a  string  containing  a  single  command  line  argument 

*  *argv  [  ]  an  array  containing  all  of  the  command  line  arguments 


file  pointer 


fptr 

inptr 

outptr 


file  pointer 
input  file  pointer 
output  file  pointer 
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structure 


*ptrlist  of  type  f  list 
with  fields: 

character  ptrlist.in  input  file 

ptrlist.out  output  damage  file 

pointer  ptriist.ptrnext  points  to  next  item  in  ptrlist  list 


Global 

Variables 

integer  mode  damage  mode  (0=EMP,  1=fallout  radiation) 

upset  switch  upset  toggle  (0=off,  1=use  upset  curves) 

live_vec  toggle  to  add  live  vector  to  output  (0=off,  1=on) 

node_dmg  toggle  to  indicate  if  node  file  is  present  (1 )  or  absent  (0) 

span_dmg  toggle  to  indicate  if  span  file  is  present  (1 )  or  absent  (0) 

ftg_dmg_ptr  pointer  to  the  Series  G  damage  CDF  curves  in  use  (e.g.,  6dB) 
ftg_ups_ptr  pointer  to  the  Series  G  upset  CDF  curves  in  use  (e.g.,  6dB) 
tot_iter  [  3  ]  number  of  Monte  Carlo  iterations  (low,  medium,  and  high) 
tot_cdf  number  of  CDF  curves  loaded 

pstog  toggle  to  use  Series  G  curves  without  power  supply  damage 

num_nodes  number  of  nodes  read  for  damage 
num_spans  number  of  spans  read  for  damage 
node_stats [6] 

counts  the  number  of  each  node  category 
span_stats [11] 

counts  the  number  of  each  span  category 
length_count  total  number  of  spans  included  for  average  length 
span_dmg_stats[ll] [2] [3] 

span  damage  stats  by  category  (out  of  1 1)  and  damage  level  (of  3) 

node_dmg_stats [ 6 ] [2] [3] 

node  damage  stats  by  category  (out  of  6)  and  damage  level  (of  3) 
stream_numi  random  number  stream  #1 

stream_num2  random  number  stream  #2 

Fcount  fiber  diagnostic  variable 

double  Fsum  fiber  diagnostic  variable 

cdf_table[MAX_CDF] [100] 

100-point  CDF  curves 
supp_cdf_table [MAX_SUP] [100] 

100-point  supplemental  CDF  curves 

length_sum  [ 1 1  ] 

sum  of  span  lengths  (by  category) 
length_sumsqr [11] 

sum  of  span  lengths  squared  (by  category) 

character  cdf _f  ile  [81]  name  of  the  main  CDF  file 

analog_switch_types [ ] 

contains  the  3-character  switch  equipment  codes  which  are  assigned 
to  the  generic  analog  switch  CDF  curve  for  damage 

digital_switch_typesl [ ] 

contains  half  of  the  3-character  switch  equipment  codes  which  are 
assigned  to  the  generic  digital  switch  CDF  curve  for  damage 

analog_switch_types2 [] 

contains  half  of  the  3-character  switch  equipment  codes  which  are 
assigned  to  the  generic  digital  switch  CDF  curve  for  damage 
nt_digital_types [ ] 
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structure 


Component 

Functions 


contains  the  3-character  switch  equipment  codes  which  are  assigned 
to  the  DMS-100  CDF  curve  for  damage 


nodefiles 
with  fields: 


of  type  flist 


character 

nodefiles . in 

input  node  file 

nodefiles. out 

output  damage  file 

pointer 

nodefiles .ptrnext 

points  to  next  item  in  nodefiles  list 

spanfiles  of 

type  flist 

with  fields: 

character 

spanfiles . in 

input  span  file 

spanfiles .out 

output  damage  file 

pointer 

spanfiles . ptrnext 

points  to  next  item  in  spanfiles  list 

EQ_list ,  EQ_ptr  of  type  EQ 

with  fields: 

character 

EQ_list . eq_type [ 4 ] 

equipment  code 

integer 

EQ_JList .  freq 

number  of  occurrences 

pointer 

EQ_1 i s  t . ptrnext 

points  to  next  item  in  EQ_list  list 

LoadKey ( ) 
TallyUnknown ( ) 

LoadCDF ( ) 
LoadSuppCDF ( ) 
detprb ( ) 

Survive ( ) 

DmgNode ( ) 
DmgSpan ( ) 
PrintNodeStats ( ) 
PrintSpanStats ( ) 


opens  and  reads  the  keyfile 

counts  the  number  of  times  an  unknown  equipment  type  is 

found  in  an  asset  file 

loads  a  CDF  file  into  memory 

loads  supplemental  CDF  data  into  memory 

picks  a  random  point  from  a  CDF  curve  and  returns  a 

probability  associated  with  that  point 

returns  a  random  survival  value  based  on  a  CDF  curve 

generates  a  series  of  damage  vectors  for  one  node 

generates  a  series  of  damage  vectors  for  one  span 

prints  summary  node  statistics 

prints  summary  span  statistics 


3-64 


Function 

Tree 


Algorithmic 

Description 


— LoadKey ( ) 

— LoadCDF ( ) 
-LoadSuppCDF ( ) 


main ( )  -h  DmgNode ( ) 


-  PrintNodeStats ( ) 

-  DmgSpan  ( )  — ■ 

- PrintSpanStats ( ) 


c 


Tal lyUnknown ( ) 
Survive  { )  —  detprb  ( ) 


—Tal lyUnknown ( ) 

-  Survive  ( )  —  detprb  ( ) 

-  detprb ( ) 


This  module  uses  equipment  survivability  data  to  determine  probabilistically  the  survival 
or  failure  of  network  equipment.  This  module  was  designed  to  interpret  CDF  curves 
representing  the  probability  of  damage  due  to  EMP  effects.  Tests  have  been 
performed  on  a  number  of  switching  and  transmission  systems.  For  each  equipment 
type,  physical  survivability  CDF  curves  were  calculated  for  each  of  the  three  EMP  stress 
levels  (low,  medium,  and  high).  In  addition,  switch  upset  CDF  curves  were  calculated  for 
four  equipment  types.  The  constants  section  above  details  the  available  EMP  CDF 
curves. 

This  set  of  equipment  represents  a  major  portion,  although  not  a  comprehensive  set,  of 
the  equipment  types  employed  in  the  PSN.  There  are  no  EMP  test  data  for  some 
network  equipment  types.  Rather  than  assume  they  survive  EMP  damage,  equipment 
types  that  have  not  been  tested  are  assigned  the  survivability  of  the  tested  equipment 
type  that  they  most  closely  resemble. 

The  general  procedure  for  testing  equipment  failure  (referred  to  as  the  “CDF  Test”)  is 
the  following: 

1)  Pick  a  random  number,  Y  (uniform  distribution,  0-1). 

2)  Find  the  x-value,  X,  on  the  CDF  curve  corresponding  to  the  y-value,  Y. 

3)  Pick  a  second  random  number,  A  (uniform  distribution,  0-1). 

4)  If  A<X  then  the  equipment  survives  the  CDF  Test,  otherwise  it  fails. 

EMP  node  damage  is  the  simplest  to  assess.  To  survive  EMP  damage,  a  node  need 
only  pass  a  single  CDF  Test  with  the  CDF  curve  to  which  the  equipment  has  been 
assigned.  To  survive  switch  upset,  a  node  must  pass  the  damage  CDF  Test  plus  an 
additional  test  with  the  assigned  EMP  upset  curve.  Switch  upset  does  not  apply  to 
equipment  assigned  to  the  Generic  Analog  CDF  curve. 

EMP  span  damage  is  more  complex.  In  general,  a  minimum  of  two  CDF  Tests  are 
required  to  determine  survival/failure — one  CDF  Test  for  each  endpoint.  However,  long 
spans  which  require  intermediate  repeater  equipment  will  require  additional  CDF  Tests 
for  the  additional  equipment.  The  assumed  spacing  between  repeaters  varies  by 
equipment  type:  23  miles  for  optical  fiber,  26  miles  for  microwave,  and  1  mile  for  T1 . 

Two  additional  exceptions  apply  to  span  damage.  First,  T1  links  longer  than  50  miles 
are  assumed  to  be  data  errors,  and  are  assigned  to  the  Series  G  optical  fiber  CDF  curve. 
Second,  LEC  spans  are  assumed  to  be  80%  fiber  and  20%  T 1 . 
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A  final  consideration  for  Series  G  fiber  damage.  Several  CDF  curves  are  available  for  this 
span  type  based  on  a  number  of  assumptions.  The  default  Series  G  curves  assume 
6dB  shielding  around  the  repeaters.  Using  the  -h  option,  the  user  may  assess  Series 
G  damage  using  the  10dB  shielding  curves.  Additionally,  the  -p  option  assess  Series 
G  damage  using  curves  which  do  not  consider  damage  to  the  equipment  power 
supplies.  Options  -h  and  -p  may  not  be  used  together. 

After  the  command  line  arguments  have  been  parsed  and  interpreted,  main  ( ) 
executes  in  the  following  order: 

1 )  Calls  LoadKey  ( )  to  open  and  interpret  the  keyfile. 

2)  Calls  LoadCDF  ( )  to  load  the  main  CDF  file. 

3)  Calls  LoadSuppCDF  ( )  to  load  the  supplemental  CDF  file,  this  file  contains  1 00 
additional  data  points  between  0.9  and  1 .0  for  certain  equipment. 

4)  For  each  node  record  in  the  first  node  file,  calls  DmgNode  ( )  to  produce  damage 
vectors  for  that  node.  DmgNode  ( )  writes  the  output  data  to  an  output  damage  file. 

5)  Calls  PrintNodeStats  ( )  to  get  summary  damage  statistics  for  the  node  file. 

6)  Prints  a  summary  of  all  unknown  switch  equipment  types  found  in  the  file. 

7)  Repeats  Steps  4  through  6  for  each  node  file  specified  by  the  keyfile. 

8)  For  each  span  record  in  the  first  span  file,  calls  DmgSpan  ( )  to  produce  damage 
vectors  for  that  span.  DmgSpan  ( )  writes  the  output  data  to  an  output  damage  file. 

9)  Calls  Print  spans  tats  ( )  to  get  summary  damage  statistics  for  the  span  file. 

1 0)  Repeats  Steps  8  and  9  for  each  span  file  specified  by  the  keyfile. 
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3.11.1  LoadKey 


function 


damage  module 


Inputs 

file  *  f ptr  •  a  file  pointer  to  the  keyfile  (already  opened) 

Outputs 

globals  integer  mode  the  damage  mode  (0=EMP,  1=fallout  radiation) 

tot_iter  [  3  ]  the  number  of  low,  medium,  and  high  iterations 
upset  toggle  for  switch  upset  (0=off,  1=on) 

character  cdf_fiie[]  the  name  of  the  main  CDF  file 

structures  nodefiles  and  spanfiles  of  type  f  list 
with  fields: 

character  in  [  ]  input  asset  file 

out  [  ]  output  damage  file 

pointer  *ptrnext  points  to  next  item  in  list 

Purpose  To  load  run  parameters  from  the  keyfile. 

Called  By  main() 


Calls  To  none 


Local 

Variables 

integer  count  holds  the  current  line  number  in  the  keyfile 

flag  error  flag 

character  line  [80]  holds  an  entire  line  from  the  keyfile 

infile  [81]  temporarily  holds  the  name  of  an  input  asset  file 

outf  ile  [81]  temporarily  holds  the  name  of  an  output  damage  file 

type  a  single  character  holding  the  type  of  asset  file  (N=node,  S=span) 

pointer  to 

structures  *ptrnew  points  to  a  new  f  list  entry  to  be  inserted  into  a  list 

*ptrlastspan  points  to  the  end  Of  the  spanfiles  list 
*ptrlastnode  points  to  the  end  Of  the  nodefiles  list 

Global 

Variables  none 
Algorithmic 

Description  This  function  reads  each  line  of  the  keyfile  and  sets  run  parameters  according  to  entries 
in  the  keyfile.  All  of  the  run  parameters  are  held  in  global  variables.  The  line-by-line 
structure  of  the  keyfile  is  shown  in  the  damage  module  description. 
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3.11.2  Load  CDF 


function 


damage  module 


Inputs 

file 

*fptr 

a  pointer  to  the  main  CDF  file  (already  opened) 

Outputs 

globals 

double 

cdf_table [MAX_CDF] [100] 

100-point  CDF  curves 

tot_cdf  the  number  CDF  curves  loaded 

Purpose 

To  load  CDF  curves  from  the  main  CDF  file. 

Called  By 

main( ) 

Calls  To 

none 

Local 

Variables 

integer 

i 

count 

tog 

pcount 

an  index  variable 

the  line  number  of  the  current  CDF  curve 

toggle  to  indicate  that  the  50%  point  has  been  passed  on  the  curve 
cycles  from  0  to  2  to  indicate  low,  medium,  or  high  stress  levels 

character 

line [100] 
temp [15] 

holds  an  entire  line  from  the  CDF  file 
used  to  parse  a  CDF  data  point  from  line 

Global 

Variables 

none 

Algorithmic 

Description 

This  function  parses  each  line  of  a  CDF  file  to  extract  5  y-values  from  a  100-point  CDF 
curve.  The  curves  are  assumed  to  be  grouped  by  the  three  EMP  stress  levels  (low, 
medium,  and  high).  The  structure  of  the  CDF  file  is  described  in  the  damage  module. 
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3.11.3  LoadSuppCDF  function 


damage  module 


Inputs 

file 

Outputs 

globals 

Purpose 
Called  By 

Calls  To 

Local 

Variables 

file 

integer 


character 


Global 

Variables 


Algorithmic 

Description 


*f tg_fd565 . cdf_supp 

the  supplemental  CDF  file  for  Series  G  and  FD-565 


double  supp_cdf_table [MAX_SUP] [100] 

1 00-point  supplemental  CDF  curves 

To  load  supplemental  CDF  curves  from  the  supplemental  CDF  file. 

main( ) 


none 


*  fptr  pointer  to  the  supplemental  CDF  file 

i  an  index  variable 

count  the  line  number  of  the  current  CDF  curve 

tog  toggle  to  indicate  that  the  50%  point  has  been  passed  on  the  curve 

pcount  cycles  from  0  to  2  to  indicate  low,  medium,  or  high  stress  levels 

line  [100]  holds  an  entire  line  from  the  CDF  file 
temp  [  15  ]  used  to  parse  a  CDF  data  point  from  line 


none 


This  function  parses  each  line  of  the  supplemental  CDF  file  to  extract  5  y-values  from  a 
100-point  supplemental  CDF  curve.  These  points  correspond  to  CDF  x-values 
between  0.9  and  1.0.  The  curves  are  assumed  to  be  grouped  by  the  three  EMP  stress 
levels  (low,  medium,  and  high).  The  structure  of  the  supplemental  CDF  file  is  identical 
to  the  main  CDF  file  (described  in  the  damage  module). 
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3.11.4  DmgNode 


function 


damage  module 


Inputs 

character 

clliA [ ] 
equip [ ] 

the  1 1 -character  switch  CLLI  code 
the  3-character  switch  equipment  code 

integer 

MODE 

UPSET 
LIVE_VEC 
tot__iter  [3] 

the  damage  mode  (0=EMP,  1=fallout  radiation) 
the  switch  upset  mode  (0=off,  1=on) 
the  toggle  to  add  an  output  live  vector  (0=off,  1=on) 
the  number  of  vectors  to  generate  (low,  medium,  high) 

file 

*outptr 

pointer  to  the  output  damage  file 

Outputs 

global 

integer  node, 
node. 

.stats  [  6  ]  counts  the  number  of  nodes  in  each  node  category 

_dmg_stats [ 6 ] [2] [3] 

node  damage  stats  by  category  (out  of  6)  and  damage 
level  (out  of  3)  where  the  middle  subscript  allows  for 
holding  live  and  damage  totals 

Purpose 

Generates  damage  vectors  for  a  single  node. 

Called  By 

main ( ) 

Calls  To 

TallyUnknown ( ) 

Survive ( ) 

Local 

Variables 

integer 

column 

upset_col 

bin 

it 

surviv 

an  index  into  the  CDF  table  pointing  to  the  damage  curve 
an  index  into  the  CDF  table  pointing  to  the  upset  curve 
the  EMP  stress  level  (0=low,  1=medium,  2=high) 
iteration  loop  variable 
node  equipment  survival  (1)  or  failure  (0) 

Global 

Variables  none 


Algorithmic 

Description  This  function  generates  the  number  of  damage  vectors  specified  by  tot_iter  [  ] . 

Damage  is  based  on  the  type  of  node  equipment  and  the  level  of  EMP  damage  being 
assessed.  Damage  may  be  based  on  EMP  or  fallout  radiation  curves  (based  on  mode), 
and  may  include  the  effects  of  switch  upset  (based  on  upset).  Finally,  a  live  damage 
vector  may  be  added  to  the  beginning  of  the  output  damage  stream  (based  on 

LIVE_VEC). 

For  a  given  node,  the  following  procedure  is  followed: 
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1)  Assign  damage  and  upset  CDF  curves  to  the  node  based  on  the  input 
equipment  type.  If  the  equipment  code  is  “unknown,”  then  call 
TallyUnknown  ( )  with  the  code.  Assume  equipment  is  of  type  5ESS. 

2)  Call  Survive  ( )  with  the  base  CDF  curve  (column)  plus  the  stress  level  (bin). 
Survive  ( )  returns  1  (survive)  or  0  (fail). 

3)  If  the  node  survives  Step  2  and  upset  is  on,  then  call  survive  ( )  with  the  upset 
CDF  cun/e  (upset_col)  plus  the  stress  level  (bin).  Survive  ( )  returns  1 
(survive)  or  0  (fail). 

4)  If  the  node  survives  both  Steps  2  and  3,  then  print  a  T  to  the  output  damage  file. 
Otherwise,  print  a  ‘O’. 

5)  Tally  up  the  damage  stats  in  node_dmg_stats  [  ] . 

6)  Repeat  Steps  2  through  5  for  the  number  of  iterations  specified  by  tot_iter  [  ] 
for  the  current  EMP  stress  level. 

7)  Repeat  Step  6  for  each  EMP  stress  level. 
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3.11.5  PrintNodeStats  function 


damage  module 


Inputs 

Outputs 

Purpose 

Called  By 

Calls  To 

Local 

Variables 

Global 

Variables 

integer 

Algorithmic 

Description 


none 

none 

To  print  summary  statistics  for  each  node  type. 

main ( ) 


none 


none 


node_stats  [  6  ]  counts  the  number  of  nodes  in  each  node  category 

node_dmg_stats [ 6 ] [ 2 ] [ 3 ] 

node  damage  stats  by  category  (out  of  6)  and  damage 
level  (out  of  3)  where  the  middle  subscript  allows  for 
holding  live  and  damage  totals 


This  function  prints  out  node  statistics.  For  each  category  equipment  (e.g.,  4ESS),  the 
total  number  of  nodes  in  the  category  are  printed,  as  well  as  the  percentage  of  all  nodes 
that  that  category  accounts  for.  Finally,  the  percentage  of  node  damaged  at  each  EMP 
stress  level  (low,  medium,  high)  is  shown. 
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3.11.6  DmgSpan 


function 


damage  module 


Inputs 

character 

integer 

file 

Outputs 

global 

Purpose 
Called  By 

Calls  To 

Local 

Variables 

integer 

double 


cliiA  [] 

the 

clliz [ ] 

the 

equip [ ] 

the 

MODE 

the 

UPSET 

the 

LIVE__VEC 

the 

tot_iter [3 ] 

the 

VA 

the 

HA 

the 

VZ 

the 

HZ 

the 

11 -character  originating  CLLI  code 
11 -character  terminating  CLLI  code 
2-character  switch  equipment  code 

damage  mode  (0=EMP,  1=fallout  radiation) 

switch  upset  mode  (0=off,  1=on) 

toggle  to  add  an  output  live  vector  (O=off,  1=on) 

number  of  vectors  to  generate  (low,  medium,  high) 

V-coordinate  of  cliiA 

H-coordinate  of  cliiA 

V-coordinate  of  clliz 

H-coordinate  of  clliz 


*outptr 


pointer  to  the  output  damage  file 


integer  span_stats[ii]  counts  the  number  of  spans  in  each  span  category 
span_dmg_stats [11] [2] [3] 

span  damage  stats  by  category  (out  of  1 1)  and  damage 
level  (out  of  3)  where  the  middle  subscript  allows  for 
holding  live  and  damage  totals 

Generates  damage  vectors  for  a  single  span. 

main( ) 


TallyUnknown ( ) 
Survive ( ) 
detprb ( ) 


column 

upset_col 

bin 

it 

surviv 

i 

n 

equip_type 


an  index  into  the  CDF  table  pointing  to  the  damage  curve 

an  index  into  the  CDF  table  pointing  to  the  upset  curve 

the  EMP  stress  level  (0=low,  1=medium,  2=high) 

iteration  loop  variable 

node  equipment  survival  (1)  or  failure  (0) 

in  index  variable 

the  number  of  times  a  CDF  Test  must  be  repeated 
a  code  number  indicating  the  equipment  category 


D 

fo__prob 

tl_prob 

probl 

prob2 


the  length  of  a  span 

the  survival  probability  of  a  LEC  fiber  span 
the  survival  probability  of  a  LEC  T1  span 
an  aggregate  survival  probability  of  a  LEC  span 
a  random  number 
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Global 

Variables 


Algorithmic 

Description 


none 


This  function  generates  the  number  of  damage  vectors  specified  by  tot_iter  [  ] . 
Damage  is  based  on  the  type  of  span  equipment,  the  length  of  the  span,  and  the  level 
of  EMP  damage  being  assessed.  Damage  may  be  based  on  EMP  or  fallout  radiation 
curves  (based  on  mode),  and  may  include  the  effects  of  switch  upset  (based  on  upset). 
Finally,  a  live  damage  vector  may  be  added  to  the  beginning  of  the  output  damage 
stream  (based  on  live_vec). 

For  a  given  span,  the  following  procedure  is  followed:  (NOTE:  Pages  9-14  of 
Reference  5  contains  a  complete  description  of  the  damage  procedure.) 

1 )  Calculate  the  length  of  the  span. 

2)  Decode  the  equipment  type  and  assign  a  code  to  variable  equip_type.  This 
code  may  reflect  a  change  in  equipment  type  (e.g.,  long  T1  s  are  assumed  to  be 
Series  G  optical  fiber).  If  the  equipment  code  is  “unknown,”  then  call 

Tai  lyUnknown  ( )  with  the  code.  Assume  the  equipment  is  of  Series  G  optical 
fiber. 

3)  Accumulate  average  length  statistics  for  the  equipment  type. 

4)  Assign  damage  and  upset  CDF  curves  to  the  span  based  on  equip_type. 

5)  For  most  equipment  types,  determine  the  number  of  repeaters  based  on  the 
span  length. 

6)  Call  survive  ( )  for  each  endpoint  and  for  each  repeater. 

7)  If  the  span  survives  all  of  the  CDF  Tests  in  Step  6  and  upset  is  on,  then  call 
Survive  ( )  for  each  endpoint  and  repeater  using  the  upset  CDF  curve.  (NOTE: 
only  Series  G  has  upset  curves. 

8)  If  the  span  survives  both  Steps  6  and  7,  then  print  a  T  to  the  output  damage  file. 
Otherwise,  print  a  ‘O’. 

9)  Tally  up  the  damage  stats  in  span_dmg_stats  [  ] . 

1 0)  Repeat  Steps  6  through  9  for  the  number  of  iterations  specified  by  tot_iter  [  ] 
for  the  current  EMP  stress  level. 

1 1 )  Repeat  Step  1 0  for  each  EMP  stress  level. 
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3.11.7  PrintSpanStats  function 


damage  module 


Inputs 

Outputs 

Purpose 

Called  By 

Calls  To 

Local 

Variables 

double 

Global 

Variables 

integer 

Algorithmic 

Description 


none 

none 

To  print  summary  statistics  for  each  span  type. 

main ( ) 


none 


mean  average  length  of  spans  in  a  category 

sdev  standard  deviation  of  the  length  of  spans  in  a  category 


span_stats  [  11  ]  counts  the  number  of  spans  in  each  span  category 
span_dmg_stats [11] [2] [3] 

span  damage  stats  by  category  (out  of  1 1)  and  damage  level  (out 
of  3)  where  the  middle  subscript  allows  for  holding  live  and 
damage  totals 


This  function  prints  out  span  statistics.  For  each  category  equipment  (e.g.,  T1 ),  the 
total  number  of  spans  in  the  category  are  printed,  as  well  as  the  percentage  of  all  spans 
that  that  category  accounts  for.  The  average  length  of  the  spans  in  the  category  is  also 
printed.  Finally,  the  percentage  of  spans  damaged  at  each  EMP  stress  level  (low, 
medium,  high)  is  shown. 
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3.11.8  TallyUnknown  function 


damage  module 


Inputs 

character 

equip [ ] 

a  3-character  equipment  code 

Outputs 

globals 

structure  EQiist  of  type  eq 
with  fields: 

character  eq_type[4]  equipment  code 

integer  freq  number  of  occurrences 

pointer  ptrnext  points  to  next  item  in  EQ_list 

Purpose 

To  maintain  a  list  of  unknown  equipment  codes  and  the  number  of  times  each  code 
appears.. 

Called  By 

DmgNode ( ) 
DmgSpan ( ) 

Calls  To 

none 

Local 

Variables 

integer 

flag 

an  indicator  variable 

pointer  to 
structures 

EO  ptr 

EO  new 
EQ_prev 

points  to  an  eq  entry 

points  to  a  new  eq  entry  to  be  inserted  into  EQ_list 
points  to  an  eq  entry 

Global 

Variables 

none 

Algorithmic 

Description 

There  are  hundreds  of  equipment  codes  in  use  in  the  LECs.  Not  all  of  these  codes 

have  been  assigned  to  a  CDF  curve.  This  routine  tallies  these  “unknown”  codes  for 
each  data  file.  Upon  being  sent  an  unknown  code,  this  routine  checks  the  existing  list 
of  codes  (EQ_list).  If  found,  then  the  number  of  occurrences  is  incremented. 
Otherwise,  the  code  is  added  to  the  end  of  the  list. 
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3.11.9  Survive  function _  _  damage  module 

Inputs 

integer  curve  a  CDF  curve  number 

Outputs 

returns  integer  returns  either  TRUE  (1)  indicating  survival  or  FALSE  (0)  indicating 

damage 

Purpose  To  determine  equipment  survivability  from  a  specified  CDF  curve. 

Called  By  DmgNode  ( ) 

DmgSpan ( ) 


Calls  To  detprb() 


Local 

Variables 

integer  answer  holds  the  return  value  (survival  or  failure) 

double  probl  a  random  probability  from  the  CDF  curve 

prob2  a  random  number  (uniform,  0-1 ) 


Global 

Variables 

integer  stream_num2  random  number  stream  #2 


Algorithmic 

Description  This  function  performs  a  single  “CDF  Test”  described  in  the  damage  module.  It  picks  a 
random  probability  from  a  specified  CDF  curve  (probl)  and  compares  it  with  a  random 
number  (prob2).  If  probi>prob2  and  probl  does  not  equal  0,  then  Survive  returns 
TRUE  (1)  indicating  equipment  survival.  Otherwise,  it  returns  FALSE  (0)  ind 
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3.11.10  detprb 


function 


damage  module 


Inputs 

integer 

Outputs 

returns 


Purpose 


Called  By 

Calls  To 

Local 

Variables 

integer 

double 


character 


Global 

Variables 

integer 

double 

Algorithmic 

Description 


curve  the  number  of  a  CDF  curve 


double  the  probability  associated  with  a  random  point  on  the  input  CDF 

curve 

This  routine  picks  a  random  point  on  the  input  CDF  curve  and  returns  the  associated 
probability.  For  Series  G  and  FD-565  optical  fiber  equipment,  supplemental  data  points 
are  read  from  supplemental  CDF  curves  to  improve  the  precision  of  the  curves.  The 
supplemental  data  is  used  if  the  random  probability  falls  between  0.9  and  1.0. 

Survive ( ) 

DmgSpan ( ) 


none 


i  an  array  index  number 

sup_tog  flag  to  indicate  that  the  supplemental  CDF’s  should  be  used 

sup_ptr  the  supplemental  CDF  curve  associated  with  the  main  CDF  curve 


point  the  random  CDF  point 

prob  the  probability  associated  with  point 


line [80] 
infile [81] 
outfile [81] 
type 


holds  an  entire  line  from  the  keyfile 

temporarily  holds  the  name  of  an  input  asset  file 

temporarily  holds  the  name  of  an  output  damage  file 

a  single  character  holding  the  type  of  asset  file  (N=node,  S=span) 


stream_numl  random  number  stream  #1 

cdf_table[MAX_CDF] [100] 

100-point  CDF  curves 
supp_cdf_table [MAX_SUP] [ 100 ] 

100-point  supplemental  CDF  curves 


For  a  specified  CDF  curve  (curve),  this  routine  returns  a  random  probability  based  on 
the  following  procedure: 

1 )  Return  0.0  if  the  first  curve  data  point  is  1 .0  (i.e.,  curve  is  all  dead). 

2)  Return  1 .0  if  the  last  curve  data  point  is  0.0  (i.e.,  curve  is  all  alive). 

3)  Pick  a  random  number,  A. 
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4)  Step  from  right  to  left  through  the  CDF  curve  until  the  y-value  of  the  current  data 
point  is  less  than  A. 

5)  Check  if  a  supplemental  CDF  curve  is  necessary. 

6)  If  not,  then  return  the  x-value  of  the  final  data  point  divided  by  1 00. 

7)  If  a  supplemental  CDF  is  necessary,  then  step  from  right  to  left  through  the 
supplemental  CDF  curve  until  the  y-value  of  the  current  data  point  is  less  than  A. 

8)  Return  the  0.9  plus  the  x-value  of  the  final  data  point  divided  by  1 000. 
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3.12  mklink:  Make  Link  module 


Purpose  This  module  assesses  the  effect  of  span  and  node  damage  on  an  IEC  network’s 

physical  transmission  paths.  Physical  damage  is  translated  into  lost  trunk  group  capacity 
in  the  logical  network. 

Call  Syntax  mklink  <filename> 

where  <f  ilename>  specifies  the  name  of  the  input  file  containing  a  list  of  all  other  input 
and  output  files 

example  mklink  MCIf  iles .  fy94 


list  file  This  file  simply  contains  the  names  of  the  three  input  files,  one 
output  file,  and  two  user-specified  parameters  to  be  used  by 
mklink.  File  names  are  limited  by  mklink  to  a  length  of  50 
characters. 

format  linel :  ccombined  trunk/path  file  name> 

Iine2:  <damaged  switch  file  name> 

Iine3:  <damaged  span  file  name> 

Iine4:  coutput  “qlink”  file  name> 

Iine5:  direction  flag  (0  =  bi-directional;  1  =  one-way) 

lineS:  damage  vector  count  (integer) 


This  file  contains  the  list  of  codes  for  IEC  backbone  switches, 
followed  by  a  user-specified  number  of  damage  vectors,  where  0 
specifies  that  the  switch  has  been  damaged,  and  1  specifies  that  it  is 
functional. 

format  <IEC  switch  CLLI  code>,  <damage  vector  string  of  0/1  ’s> 

(cl  1 ,  lx,  n(il)),  where  n  is  number  of  damage  vectors 

example  admdtxoioit  lioiiinooiioi 


This  file  contains  the  list  of  IEC  network  spans,  specified  by  the  span 
endpoint  codes,  followed  by  a  user-specified  number  of  damage 
vectors.  Span  endpoint  codes  that  are  not  full  1 1 -character  CLLI 
codes  are  padded  with  blanks. 

format  <endpoint  A  code>,  <endpoint  B  code>,  <damage  vector  string  of 
0/1 ’s> 

(cl  1 ,  lx,  cl  1 ,  lx,  n(il)),  where  n  is  number  of  damage  vectors 

example  akrnohxx  albqnm2505t  lioiiinooiioi 

trunk/path  file  This  is  the  file  produced  by  the  mkpath  module,  which  details  how 
many  trunks  traverse  each  physical  path  in  the  IEC  network.  The  file 
specifies  the  IEC  switch  CLLI  codes  of  the  trunk/path  endpoints,  the 
number  of  trunks  in  the  A  to  Z  direction  (or  all  bi-directional  trunks), 
the  number  of  trunks  in  the  Z  to  A  direction  (only  used  for  one-way 


input 

Files 
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Output 

Files 


Includes 

Constants 


Global 

Variables 

file 

integer 

character 

structure 


trunk  groups),  and  a  series  of  span  index  numbers  that  define  the 
physical  transmission  path. 

format  <switch  inaex  A>,  <switch  index  Z>,  <A->Z  trunk  quantity;*,  <Z->A 
trunk  quantity;*,  <span1  >,  <span2>, ... ,  <span  n> 

(i6,  i6,  i6,  i6,  [spans:]  i6,  i6 . i6) 


output 

lg.lj.nk’  file  This  file  essentially  replaces  the  path  information  (string  of  span 

indices)  from  the  trunk/path  file  with  a  damage  vector  that  indicates 
whether  the  path  is  damaged.  In  addition,  since  there  is  only  one 
trunk  size  field  in  each  qlink  output  record,  a  one-way  Z->A  trunk 
group  (the  second  trunk  group  field  in  the  input  trunk/path  file)  is 
handled  by  creating  a  second  qlink  record,  with  the  endpoints  placed 
in  reverse  order.  In  this  sense,  the  ordering  of  endpoints  in  the  qlink 
file  may  represent  the  directionality  of  the  trunk  group.  A  record 
number  has  been  added  as  the  first  field. 

format  crecord  #>,  <switch  index  A>,  <switch  index  Z>,  <trunk  quantity>, 
<damage  vector  string  of  0/1  ’s> 

(i5,  i4,  i4,  i4,  lx,  n(il)),  where  n  is  number  of  damage  vectors 

example  391  22  23  48  llOlllllOOllOl 

392  22  24  96  01110111101011 


<stdio.h> 

<string.h> 

<math.h> 

"fileio.c"  See  Appendix  B 


MAXLENGTH 

4000 

CLLI_LNG 

12 

MAX_ITER 

101 

PATHPRINT 

9 

DMGPRINT 

84 

MAX_SPAN_REC  9000 

maximum  number  of  characters  in  a  path  file  record 
length  of  a  switch  CLLI  code,  including  terminating  null  character 
maximum  number  of  switch  and  span  damage  vectors  allowed 
defines  a  path  record  case  for  which  to  print  debug  data 
defines  a  damage  vector  case  for  which  to  print  debug  data 
maximum  number  of  records  in  the  span  file 


*pathf ile,  *switchfile,  *spanfile,  *filelist,  *linkfile 

pointers  to  the  input  and  output  files 

direction  indicates  use  of  bi-directional  (0)  or  one-way  (1 )  trunk  groups 
damage_vec  specifies  number  of  damage  vectors  in  each  damaged  switch  and 
span  file  record 

span_damage [MAX_SPAN_REC] [MAX_ITER] 

holds  the  damage  vectors  for  each  span  file  record  (e.g., 
span_damage  [390-1]  [4-1]  specifies  the  fourth  damage  vector 
for  span  index  390) 

sw[200]  of  type  switch_struct 
with  fields: 

character  sw  [  ] .  clli  used  to  hold  the  list  of  switch  CLLI  codes 

character  sw  [  ] .  damage  used  to  hold  the  switch  damage  vectors 
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Component 

Functions  openfilesO  opens  input  and  output  files 

readswitches  ( )  reads  in  the  list  of  switches  and  switch  damage  vectors  from 

the  damaged  switch  file 

readspans  ( )  reads  in  the  list  of  spans  and  span  damage  vectors  from 

the  damaged  span  file 

createlink  ( )  maps  damage  to  each  trunk/path  record  and  generates 

output  file 

closef  iles  ( )  closes  input  and  output  files 

Function 

Tree 

-openf iles ( ) 

—  readswitches ( ) 
main  ( )  —  *  readspans  ( ) 

—  createlink ( ) 

—  closef iles { ) 

Algorithmic 

Description  The  physical  IEC  network  is  composed  of  switches  and  spans  (e.g.  repeater-to-repeater 
transmission  segments).  Damage  to  switches  and  spans  is  represented 
deterministically  as  a  set  of  scenarios,  or  damage  vectors,  where  a  value  of  0  represents 
failure  of  that  asset,  and  a  value  of  1  represents  no  damage.  The  purpose  of  this 
module  is  to  determine  the  effect  of  damaged  switches  and  spans  on  the  logical  IEC 
network  (i.e.  point-to-point  trunk  group  sizes).  Damage  to  these  individual  network 
components  is  mapped  to  an  entire  physical  transmission  path  (two  switch  endpoints 
connected  by  a  series  of  spans)  to  determine  if  the  path  fails  or  survives.  The  logical 
network  capacity  is  then  adjusted  for  damage  based  on  the  number  of  trunks  that 
traverse  the  path. 

Mkiink  is  an  important  module  because  it  maps  physical  damage  onto  the  logical 
network,  so  that  the  significant  quantity  of  physical  path  data  does  not  need  to  be 
carried  forward  in  the  data  flow  to  subsequent  TAMI  modules.  The  output  ‘qlink’  file  will 
contain  the  pool  of  IEC  network  damage  scenarios  required  for  the  Monte  Carlo 
sampling  methodology  employed  by  TAMI. 

The  module  requires  two  user-specified  run-time  parameters,  scanned  in  from  line  5 
and  6  of  the  input  file.  The  first  is  a  direction  flag,  which  tells  the  module  whether  it 
should  look  for  one-way  trunk  group  quantities  (in  both  the  A->Z  and  Z->A  columns  of 
the  trunk/path  file)  or  a  single  bi-directional  trunk  group  quantity  from  the  A->Z  column. 
The  second  option  is  the  damage  vector  count.  This  parameter  tells  the  module  how 
many  damage  vectors  to  expect  to  read  from  the  damaged  switch  and  span  files. 

The  goal  of  this  module  is  to  evaluate  each  record  in  the  trunk/path  file  for  damage, 
replacing  the  long  series  of  span  indices  with  a  string  of  evaluated  0/1  values  that 
indicate  whether  the  path  is  damaged  or  functional  for  each  damage  vector.  To 
evaluate  the  effect  of  the  n^  damage  vector  on  a  path,  the  following  series  of  lookups 
is  performed: 

1 )  For  each  path  endpoint,  look  up  the  n**1  damage  vector  in  the  list  of  damaged 
switches.  If  either  switch  endpoint  is  damaged,  the  entire  path  is  damaged;  if  not, 
we  must  continue  evaluating  damage  in  the  next  step. 
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2)  For  each  span  in  the  path  record,  look  up  the  n^  damage  vector  in  the  damaged 
span  file.  If  the  span  is  damaged,  the  entire  path  is  damaged;  if  not,  we  must 
continue  evaluating  damage  for  the  next  span  in  the  path. 

3)  If  both  switch  endpoints  and  all  of  the  spans  in  a  path  are  undamaged,  then  the 
path  is  undamaged;  if  at  least  one  part  of  the  path  is  damaged,  the  entire  path  is 
damaged. 

The  qlink  output  file  format  only  supports  one  trunk  quantity  field;  therefore,  in  the  case 
of  one-way  trunk  groups,  a  trunk/path  record  containing  both  an  A->Z  and  a  Z->A  trunk 
quantity  will  result  in  two  qlink  output  records,  the  first  with  endpoints  A  and  Z,  and  the 
second  with  endpoints  Z  and  A. 

The  code  for  this  module  is  straightforward.  The  main  ()  routine  passes  the 
<f  iiename>  argument  into  openf  iles  ( ) ,  which  opens  input  and  output  files  and 
reads  in  the  user-specified  directional  flag  and  number  of  damage  vectors.  It  then  calls 
readswitches  ( )  and  readspans  ( )  to  load  the  list  of  switches  and  corresponding 
damage  vectors,  and  spans  and  corresponding  damage  vectors,  createlink  ( )  is 
called  next  to  perform  the  damage  checking  algorithm  described  above.  This  routine 
reads  in  a  trunk/path  record,  evaluates  the  switch  endpoints  for  damage,  and  if 
necessary,  evaluates  each  component  span  for  damage.  Results  are  printed  directly  to 
the  output  file.  If  one-way  trunk  groups  are  being  employed,  the  createlink  ( ) 
function  will  print  two  qlink  output  records-one  for  each  direction,  ciosef  iles  ( )  is 
called  to  close  all  open  files  before  the  module  terminates. 
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3.12.1  openfiles 


function 


mklink  module 


Inputs 

character 

Outputs 

global 


returns 

Purpose 

Called  By 

Calls  To 

Local 

Variables 

character 

Global 

Variables 

Algorithmic 

Description 


files  string  containing  the  name  of  the  file  that  lists  five  input/output  files,  a 
trunk  group  directionality  indicator  and  a  damage  vector  count 


file 


integer 


*f ilelist 
*pathf ile 
*switchfile 
*spanf ile 
*linkfile 


points  to  the  file  whose  name  is  contained  in  the  files 
string 

points  to  a  file  that  contains  information  on  the  physical 
paths  and  trunk  sizes 

points  to  a  file  that  contains  information  on  damage  to  the 
backbone  network  switches 

points  to  a  file  that  contains  information  on  damage  to  the 
backbone  network  spans 
output  QTCM  link  file 


direction  equals  1  if  uni-directional  trunk  groups  are  being  used 
damage_vec  the  number  of  damage  vectors  in  the  switch  and  span 
damage  files 


no  formal  values  are  returned 

To  open  path,  switch  and  span  input  files  and  the  QTCM-link  output  file,  and  to  read  in 
the  trunk  group  directionality  indicator  vector  and  the  damage  vector  count. 

main ( ) 

none 


temp  file  [  80  ]  this  variable  is  used  temporarily  to  hold  the  name  of  the  next  file  to  be 
opened  and  read  in  from  the  list  of  files  in  f  ilelist 


none 


This  function  opens  the  file  whose  name  is  stored  in  the  string  files,  setting  a 
filepointer  to  f  ilelist .  Filelist  contains  a  list  of  all  the  input  files  to  be  opened 
in  the  following  order:  pathfile,  switchfile,  spanfile,  and  linkfile.  It 
also  contains  a  trunk  group  directionality  indicator,  direction,  and  a  damage  vector 
count,  damage_vec .  This  function  opens  each  of  the  input/output  files,  in  the  order 
they  are  read  in  from  filelist. 

Errors  encountered  during  any  file  opening  operation  result  in  an  error  message  being 
printed  to  the  screen,  and  termination  of  the  module. 
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3.12.2  readswitches 


function 


mklink  module 


Inputs 

Outputs 

global 


returns 

Purpose 

Called  By 

Calls  To 

Local 

Variables 

integer 


float 

character 

Global 

Variables 

file 

Algorithmic 

Description 


none;  operates  on  global  variables 

switch_struct  structure  sw  [  ] 
with  field 

character  swU.clli 

sw[]  .damage 


used  to  hold  each  record  in  the  switch 
file 

holds  switch  endpoints  read  in  from  the 
switchfile 

holds  damage  vectors  for  the  switches 


no  formal  values  are  returned 

To  read  the  list  of  switch  CLLI  codes  and  damage  vectors  from  the  switch  damage  file 
into  the  sw  [  ]  structure,  and  to  compute  summary  switch  survivability  statistics. 

main ( ) 

none 


i  r  j 

num_nodes 

num_live 

dam_temp 

len 


general  loop  count  variables 

counts  the  number  of  records  read  in  from  the  switch  file 
counts  the  number  of  undamaged  switches  for  a  given  damage 
vector 

temporarily  holds  the  damage  vector  read  in  from  the  sw  [  ]  structure 
toggle  indicating  end-of-file  or  length  of  valid  record 


num_surv 

min_surv 

max_surv 

tot_surv 


the  switch  survivability  percentage  for  the  current  damage  vector 
minimum  percentage  of  surviving  switches 
maximum  percentage  of  surviving  switches 
the  sum  of  the  values  of  num_surv 


line  [  ]  used  to  hold  a  line  of  input  from  the  switch  file 


*  switchfile  points  to  the  switch  file 


This  function  has  two  distinct  sections. 

The  first  section  reads  the  switch  file  line  by  line,  loads  each  CLLI  code  and  damage 
vector  into  the  sw[  ]  structure,  sets  num_nodes  equal  to  the  number  of  switches,  and 
prints  out  num_nodes  to  the  screen. 

The  second  section  computes  a  number  of  switch  survivability  statistics,  including  the 
cases  (damage  vectors)  that  result  in  minimum  and  maximum  switch  survivability  over  all 
damage  vectors 
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3.12.3  readspans 


function 


mklink  module 


Inputs  none;  operates  on  global  variables 

Outputs 

global  character  span_damage  [  ]  used  to  hold  the  span  damage  vector  from  the 

span  file 


returns  no  formal  values  are  returned 

Purpose  To  read  the  list  of  span  damage  vectors  from  the  span  damage  file,  into  the 

span_damage  array,  computing  summary  survivability  statistics  in  the  process. 

Called  By  main ( ) 

Calls  To  none 

Local 

Variables 

integer  i,  j  general  loop  count  variables 

num_spans  counts  the  number  of  records  read  in  from  the  span  file 

num_live  counts  the  number  of  spans  that  are  not  marked  as  damaged  in  the 

span_damage  array 

dam_temp  temporarily  holds  the  value  read  in  from  the  span_damage  array 
len  boolean  toggle  indicating  end-of-file 

float  num_surv  percentage  of  surviving  spans  for  a  given  damage  vector 

min_surv  minimum  percentage  of  surviving  spans 
max_surv  maximum  percentage  of  surviving  spans 

tot_surv  the  sum  of  the  values  of  num_surv,  used  to  calculate  average 
survival  percentage  over  all  damage  vectors 

character  iine[]  used  to  hold  a  line  of  input  from  the  span  file 

Global 

Variables 

file  *spanf  ile  points  to  the  span  file 

Algorithmic 

Description  This  function  has  two  distinct  sections 

The  first  section  reads  the  span  file  line  by  line,  loads  each  damage  vector  into  the 
span_damage  array,  sets  num_nodes  equal  to  the  number  of  spans,  and  prints 
num_nodes  to  the  screen  as  a  summary  statistic. 

The  second  section,  computes  further  summary  statistics,  including  the  minimum  and 
maximum  survivability  for  a  given  damage  vector,  and  the  average  survivability  over  all 
damage  vectors.  For  each  damage  vector  in  the  span_damage  array,  it  parses  the 
vector,  character  by  character,  and  loads  each  character  into  a  temporary  variable, 
dam_temp.  If  the  span  is  undamaged,  this  routine  increments  the  functional  span 
counter,  num_live 
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After  the  number  of  functional  spans  has  been  counted,  this  routine  calculates  the 
span  survival  percentage  (the  ratio  of  functional  spans  to  total  spans)  and  adds  this 
result  to  a  running  total,  tot_surv. 

As  the  function  computes  span  survivability  percentages  for  each  damage  vector,  it 
keeps  track  of  the  minimum  and  maximum  span  survivability. 

Finally  this  function  prints  the  minimum  and  maximum  span  survivability  of  a  single 
damage  vector,  and  the  average  span  survivability  over  all  damage  vectors. 
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3.12.4  createlink 


function 


mklink  module 


Inputs  none;  operates  on  global  variables 

Outputs 

returns  no  formal  values  are  returned;  outputs  are  written  directly  to  the  output  file. 

Purpose  To  map  damage  to  each  trunk/path  record,  replacing  the  long  series  of  span  indices 

with  a  string  of  evaluated  0/1  values  that  indicate  whether  the  path  is  damaged  or 
functional  for  each  damage  vector,  and  to  generate  an  output  file. 

Called  By  main( ) 

Calls  To  none 

Local 

Variables 

* 

general  loop  count  variables 
the  string  length  of  a  pathf  ile  line 
the  number  of  trunks  in  the  A  ->Z  direction 
the  number  of  trunks  in  the  Z  ->A  direction 
the  originating  path  endpoint 
the  terminating  path  endpoint 
originating  switch  endpoint  damage  value,  0/1 
terminating  switch  endpoint  damage  value,  0/1 
the  number  of  spans  in  a  path  record 
the  number  of  spans  in  the  shortest  path  in  the  pathfile 
the  number  of  spans  in  the  longest  path  in  the  pathfile 
the  sum  of  the  values  of  num_spans  for  all  paths 
toggle  for  value  of  switch  endpoint  damage,  0/1 
the  current  record  number  of  the  output  file,  linkf  ile 
the  current  record  number  for  the  input  trunk/path  file 
loop  count  variable  for  reading  variable  number  of  spans  for  each 
path 

character  line  [  ]  temporarily  holds  a  line  of  input  from  the  trunk/path  file 

directline  [  ]  temporarily  holds  a  line  of  output  for  the  qlink  file 
tmpi  [  ]  temporarily  holds  originating  switch  endpoint  damage  value  ,  0/1 

tmp2  [  ]  temporarily  holds  terminating  switch  endpoint  damage  value,  0/1 

span  [  ]  temporarily  holds  span  damage  vector 

Global 

Variables 

integer  direction  indicates  use  of  bi-directional  (0)  or  one-way  (1 )  trunk  groups 

damage_vec  specifies  number  of  damage  vectors  in  each  damaged  switch  and 
span  file  record 


integer  i ,  j 

length 

trkl 

trk2 

swl 

sw2 

dmgl 

ding  2 

num_spans 

min_spans 

raax_spans 

tot_spans 

dead 

count 

num _path 

loop 
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Algorithmic 

Description 


This  function  processes  the  trunk/path  file  record-by-record,  loading  the  path 
endpoints  and  the  number  of  trunks. 

In  order  to  evaluate  the  effect  of  the  n^  damage  vector  on  a  path,  the  following 
algorithm  is  executed:  for  each  path  endpoint,  this  function,  looks  up  the  n^  damage 
vector  in  the  list  of  damaged  switches.  If  either  switch  endpoint  is  damaged,  the  entire 
path  is  damaged;  if  not,  the  function  evaluates  each  span  in  the  path  record.  For  each 
span,  this  function  ,  look  up  the  nth  damage  vector  in  the  damaged  span  file.  If  the  span 
is  damaged,  the  entire  path  is  damaged;  if  not,  this  function  evaluates  the  next  span  in 
the  path  for  damage.  If  both  switch  endpoints  and  all  of  the  spans  in  a  path  are 
undamaged,  then  the  path  is  undamaged;  if  at  least  one  part  of  the  path  is  damaged, 
the  entire  path  is  damaged.  Results  are  printed  directly  to  the  linkf  ile  output  file.'  If 
one-way  trunk  groups  are  being  employed,  this  function  will  print  two  qlink  output 
records-one  for  each  direction. 
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3.12.5  closefiies 


function 


mklink  module 


Inputs 

none 

Outputs 

global 

file  *pathfile 

points  to  the  file  that  contains  combined  the  physical 
paths  and  trunk  sizes  between  switch  pairs 

*switchfile 

points  to  file  that  describes  damage  to  the  backbone 
network  switches 

*spanf ile 

points  to  a  file  that  describes  damage  to  the  backbone 
network  spans 

*linkfile 

output  QTCM  link  file 

returns 

no  formal  values  are  returned 

Purpose 

To  close  path,  switch  and  span  input  files  and  the  QTCM  link  output  file. 

Called  By 

main ( ) 

Calls  To 

none 

Local 

Variables 

none 

Global 

Variables 

none 

Algorithmic 

Description 

This  function  closes  the  files  whose  names  are  pointed  to  by  the  following  pointers: 

pathfile,  switchfile,  spanfile  and  linkfile,  in  the  order  given. 
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Appendix  A:  ICF  File  Format  Descriptions 


The  OMNCS  maintains  information  regarding  the  IEC  networks  in  a  format  based  on  an  indexed 
chained  format  (ICF).  The  TAMI  model  requires  this  data  to  be  converted  into  a  format  for  use  in  TAMI 
analysis.  Four  of  the  modules  concern  themselves  with  re-arranging  the  ICF  data  files  into  TAMI  data  files: 
span_make,  array_make,  mk_ncam_path  and  array_make .  This  TAMI  data  structure  more  readily 
lends  itself  to  the  type  of  processing  performed  in  TAMI.  The  following  is  a  brief  discussion  of  the  ICF 
format. 


ICF  NETWORK  DATA  FILE  FORMAT 

The  purpose  of  this  file  format  is  to  specify  a  structure  that  ensures  a  common  data  input  for 
various  network  simulation  models.  The  file  format  is  based  on  an  indexed  chained  format  (ICF).  All  raw 
network  data  will  be  converted  into  ICF.  The  ICF  consists  of  data  files  cross  indexed  in  order  to  provide 
fast  disk  access.  This  format  allows  coherent  logical  subsets  of  the  network  data  to  be  quickly  and  easily 
loaded  into  simulation  models.  Thus,  every  model's  data  input  will  be  standardized. 

The  ICF  representation  of  each  network  consists  of  four  files:  node  data  file,  link  data  file,  CG  data 
file,  and  a  path  data  file.  The  damage  and  routing  files  for  each  network  will  not  be  in  ICF. 

Each  file  has  a  header  record  which  identifies  the  network  and  the  ICF  file.  The  headers  have  the 
format  XXX  <File>  where  XXX  is  the  network  (FPS  for  FPSC,  FCA  for  FCAP,  MCI  for  MCI,  and  SPR  for 
Sprint).  <File>  can  be  "link",  "path",  "trnk"  and  "node”  for  the  link,  pid,  eg  or  node  files,  respectively.  The 
length  of  the  header  record  is  the  same  length  as  the  other  records  in  that  file. 

The  following  sections  will  detail  each  file  with  an  example. 

NODE  DATA  FILE:  •  Sorted  by  node  index  and  CLLI 

•  All  fields  are  left  justified. 

•  All  records  end  with  a  carriage  return. 

The  node  data  file  contains  the  assets  of  the  network. 


Node 

cm 

Link 

Link 

V 

H 

Extra 

idx 

code 

Head 

Tail 

Cd. 

Cd. 

(Reserved) 

14 

Cll 

14 

14 

14 

mmm 

C33 

123 

BLTMD023 

11 

12 

1234 

4567 

125 

CHC1L009 

13 

30 

3343 

1233 

134 

KANM0008 

if 

31 

2334 

2445 

.  : 

ill 

'  :  :  .  ; 

Total  record  size  =  65  bytes 

LINK  DATA  FILE:  Sorted  by  link  idx 

All  fields  are  left  justified. 

All  records  end  with  a  carriage  return. 
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The  link  data  file  contains  the  physical  connections  in  the  network.  The  type  of  link  is  also 
represented.  The  link  head  from  the  node  data  file  points  to  the  first  record  in  a  block  of  records.  The  link 
tail  references  the  last  block. 

In  this  example,  node  123  (BLTMD023)  is  connected  to  125  (123  125);  123  o  456;  123 

23;  123  <->654;  123  <->230. 


Link 

idx 

Node 

Idx 

Type 

Con. 

Node 

Idx 

Type 

Con. 

Node 

Idx 

Type 

Con. 

Node 

Idx 

Type 

Con. 

14 

14 

a 

14 

Cl 

14 

Cl 

14 

Cl 

11  If 

125 

D 

456 

D 

23 

G 

654 

R 

12 

230 

D 

"  :::  ■'  '  ' 

-  %  :  ■  :  ^ 

13 

4566 

Y 

223  ft 

T 

211 

T 

1211 

T 

14 

32 

N 

211 

W  : 

1111 

’ 

It!  iff 

112 

W 

.  :  :  -  • 

: 

liilSffnif 

Total  record  size  =  25  bytes 
Link  Types 


blank 

C 

D 

E 

G 

I 

L 

N 

P 

R 

T 

U 

V 

w 

Y 

z 


Undefined 
(MCI)  Cable 
Digital  T-Carrier 
Digital  Zero  Loss  trunks 
Analog  Zero  Loss  trunks 

Analog  Satellite 

Analog  L-Carrier  L3,  L4,  L5 

Analog  N-Carrier 

Undefined  Assumed  inter-building  link  (used  in  AT&T  data) 

Analog  Radio  systems 

Analog  Coaxial  Systems  T4 

Undefined  Hybrids 

Digital  Generic  Future  Digital  Technology 

Digital  Fiber  Optic 

Digital  Radio  Systems 

Digital  Leased  Digital  Capacity 


CG  DATA  FILE:  Sorted  by  CG  idx 

All  fields  are  left  justified. 

All  records  end  with  a  carriage  return. 

The  CG  data  file  contains  the  logical  connections  of  the  network.  The  path  head  points  to  the  first 
record  in  a  block  of  records  in  the  path  data  file.  The  path  tail  references  the  last  block.  These  records 
detail  the  physical  paths  that  comprise  the  CG.  Node  A  and  node  Z  reference  the  node  data  file,  which  are 
the  node  end  points  of  the  trunk  group.  The  TRK  qty  specifies  the  number  of  trunks  in  a  trunk  group. 

The  type  identifies  the  grade  of  service  of  the  CG,  and  the  dir  field  specifies  the  direction  of  the  CG  trunk. 
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GG 

Idx 

Path 

Head 

Path 

Tail 

Node  A 
Idx 

NodeZ 

Idx 

TRK 

Qtv 

Dir 

Type 

Extra 

(Reserved) 

15 

16 

16 

14 

14 

14 

Cl 

C2 

C6 

1 

2 

3 

32  . 

34 

38 

33 

37 

34 

123 

125 

125  :: 

125 

140 

140 

23 

21 

[12 

B 

A 

DN 

AF 

PH 

'  :  : 

■■  : ' 

Total  record  size  =  39  bytes 


CG  Types: 

FT  Intermachine  Trunk 

PH  Primary  High  Usage 

AF  Alternate  Final 

DN  Dynamic  Nonhierarchial 

DIRECTION: 


B  Bi-directional 

A  From  A  to  Z 

Z  From  Z  to  A 

blank  Bi-directional 


PATH  DATA  FILE:  •  Sorted  by  Path  idx 

•  All  fields  are  left  justified. 

•  All  records  end  with  a  carriage  return. 


The  path  data  file  contains  the  paths  and  the  nodes  of  a  CG. 
one  path,  pid  no.  1  and  it  is  comprised  of  the  nodes: 


For  example  CG  idx  1  contains  only 


123  134  231  12  16  24  46  25  55  <-»  42  o  223  o  456  125. 

CG  idx  2  has  three  paths,  pid  nos.  2,  3,  and  4. 


CG  idx  3  has  one  path,  pid  no.  5. 
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Appendix  B:  User-Defined  Utility  Functions 


Functions  that  are  repeatedly  utilized  by  more  than  one  module  have  been  placed  in  this  appendix  in 
order  to  make  them  readily  available.  These  “utility”  functions  are  divided  into  two  groups: 

1)  Function  calls  repeatedly  coded  into  various  modules 

f get  ( ) 
char_comp ( ) 

2)  Function  calls  included  in  include  ’’fileio.c”: 

parse ( ) 
parse_int ( ) 
getline ( ) 
fopenfile ( ) 
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fget  function 


Inputs 

integer 

fP 

num 

a  pointer  to  a  file,  equivalent  to  type  file 

indicates  the  number  of  bytes  to  read  from  the  current  position 

long 

integer 

pos 

indicates  a  position  within  the  file  pointed  to  by  fp 

character 

data 

the  buffer  to  hold  data  read  from  the  file 

Outputs 

returns 

integer 

returns  the  number  of  bytes  read,  or  -1  if  error 

Purpose 

This  function  reads  a  specified  number  of  characters  into  a  string  buffer  from  a  given 
position  within  the  input  file. 

Local 

Variables 

none 

Global 

Variables 

none 

Algorithmic 

Description 

This  utility  I/O  function  uses  the  <stdio .  h>  function,  f  seek  ( ) ,  to  set  the  file  pointer 

fp  to  position  pos,  the  position  of  the  first  byte  to  be  read.  The  function  then  uses 
f  read  ( )  to  read  num  bytes  into  buffer  string  data.  If  there  is  an  error,  a  value  of  -l  is 
returned;  otherwise,  the  return  value  specifies  the  number  of  bytes  read. 


B-2 


char_comp  function 


Inputs 


character 

*cmpl 

points  to  the  first  string  passed  into  char  comp  ( )  for 
comparison 

*cmp2 

points  to  the  second  string  passed  into  char  comp  ( )  for 
comparison 

Outputs 

returns 

integer 

this  function  returns  a  0  if  the  two  strings  are  equal,  and  returns  a 
non-zero  if  they  are  different 

Purpose 

To  compare  two  character  strings,  for  use  in  sorting  (gsort  ( ) )  and  searchinq 
(bsearch ( ) ) 

Local 

Variables 

none 

Global 

Variables 

none 

Algorithmic 

Description  This  function  is  used  by  bsearch  ( )  and  gsort  ( )  to  compare  two  strings.  The 

arguments  cmpi,  cmp2  are  passed  into  the  standard  ‘C’  strcmp  function,  and  the 
result  is  used  as  the  char_comp  ( ) '  s  return  value.  The  result  is  0  if  cmpi=cmp2,  and 
non-zero  otherwise. 
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file  *fopenfile(filename,  type) 


fileio.c 


This  utility  function  is  a  simple  modification  of  the  standard  ‘C’  f  open  function.  It  opens  the  passed  in 
filename  and  checks  for  an  error  in  the  file.  If  an  error  exists  the  function  is  exited. 

void  parse(start,  num,  buffer,  rtn)  fileio.c 


This  utility  function  reads  num  characters  from  the  input  character  string  buffer  starting  at  position  start 
and  directs  the  output  to  the  character  string  rtn . 

int  parse_int(start,  num,  buffer) _ fileio.c _ 

This  utility  function  reads  num  characters  from  the  input  character  string  buffer  starting  at  position  start 
and  returns  the  integer  value  of  the  characters 


int  getline(fildes,  buf) _ fileio.c 

This  utility  function  reads  from  the  file  f  ildes  until  the  first  end-of-line  character  is  reached,  and  directs 
the  output  to  the  buffer  buf 
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List  of  Acronyms 


AT&T  American  Telephone  &  Telegraph 

CSF  Cumulative  Distribution  Function 

IEC  Inter-Exchange  Carrier 

ICF  Indexed  Chain  Format 

LEC  Local  Exchange  Carrier 

MCI  MCI  Telecommunication  Corporation 

NCAM  Network  Connectivity  Analysis  Model 

NCS  National  Communication  System 

NLP  National  Level  NS/EP  Telecommunications  Program 

NS/EP  National  Security  and  Emergency  Preparedness 

NT  National  Communications  System  (OMNCS)  Office  of  Technology  and  Standards 

OMNCS  Office  of  the  Manager,  National  Communication  System 

PSN  Public  Switched  Network 

QTCM  Queuing  Traffic  Congestion  Model 

TAMI  Traffic  Analysis  by  Method  of  Iteration 

TG  Trunk  Group 
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